Skip to content

Commit

Permalink
lightning: add docs for local backend (pingcap#3979)
Browse files Browse the repository at this point in the history
* lightning: add local backend

* fix

* fix

* add advice for choosing backend

* remote duplicated blank line

* update to match local backend

* fix style

* update

* fix anchor

* fix comments and links

* update architecture image

* fix typo

* fix comments

* Apply suggestions from code review

* Update tidb-lightning/tidb-lightning-backends.md

* Apply suggestions from code review

* fix review comments

* fix review comments

Signed-off-by: glorv <[email protected]>

* Apply suggestions from code review

* clarify heading

* resolve review comments

* Update tidb-lightning/tidb-lightning-backends.md

* Apply suggestions from code review

* Update tidb-lightning/tidb-lightning-configuration.md

* Update tidb-lightning/tidb-lightning-overview.md

Co-authored-by: TomShawn <[email protected]>
  • Loading branch information
glorv and TomShawn authored Aug 3, 2020
1 parent e2b24f3 commit 3a2891d
Show file tree
Hide file tree
Showing 17 changed files with 547 additions and 425 deletions.
2 changes: 1 addition & 1 deletion TOC.md
Original file line number Diff line number Diff line change
Expand Up @@ -187,7 +187,7 @@
+ [断点续传](/tidb-lightning/tidb-lightning-checkpoints.md)
+ [表库过滤](/table-filter.md)
+ [CSV 支持](/tidb-lightning/migrate-from-csv-using-tidb-lightning.md)
+ [TiDB-backend](/tidb-lightning/tidb-lightning-tidb-backend.md)
+ [导入模式](/tidb-lightning/tidb-lightning-backends.md)
+ [Web 界面](/tidb-lightning/tidb-lightning-web-interface.md)
+ [监控告警](/tidb-lightning/monitor-tidb-lightning.md)
+ [故障诊断](/troubleshoot-tidb-lightning.md)
Expand Down
2 changes: 1 addition & 1 deletion backup-and-restore-using-dumpling-lightning.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,4 +80,4 @@ Could not read data from testSchema.testTable: GC life time is shorter than tran

## 向 TiDB 恢复数据

使用 TiDB Lightning 将之前导出的数据导入到 TiDB,完成恢复操作。具体的使用方法见 [TiDB Lightning 使用文档](/tidb-lightning/tidb-lightning-tidb-backend.md)
使用 TiDB Lightning 将之前导出的数据导入到 TiDB,完成恢复操作。具体的使用方法见 [TiDB Lightning 使用文档](/tidb-lightning/tidb-lightning-backends.md)
2 changes: 1 addition & 1 deletion backup-and-restore-using-mydumper-lightning.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,4 +91,4 @@ aliases: ['/docs-cn/dev/how-to/maintain/backup-and-restore/mydumper-lightning/',

## 向 TiDB 恢复数据

使用 TiDB Lightning 将之前导出的数据导入到 TiDB,完成恢复操作。具体的使用方法见 [TiDB Lightning 使用文档](/tidb-lightning/tidb-lightning-tidb-backend.md)
使用 TiDB Lightning 将之前导出的数据导入到 TiDB,完成恢复操作。具体的使用方法见 [TiDB Lightning 使用文档](/tidb-lightning/tidb-lightning-backends.md)
2 changes: 1 addition & 1 deletion dumpling-overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -205,7 +205,7 @@ update mysql.tidb set VARIABLE_VALUE = '720h' where VARIABLE_NAME = 'tikv_gc_lif
update mysql.tidb set VARIABLE_VALUE = '10m' where VARIABLE_NAME = 'tikv_gc_life_time';
```

最后,所有的导出数据都可以用 [Lightning](/tidb-lightning/tidb-lightning-tidb-backend.md) 导入回 TiDB。
最后,所有的导出数据都可以用 [Lightning](/tidb-lightning/tidb-lightning-backends.md) 导入回 TiDB。

## Dumpling 主要选项表

Expand Down
9 changes: 5 additions & 4 deletions ecosystem-tool-user-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,10 +22,11 @@ aliases: ['/docs-cn/dev/reference/tools/user-guide/','/docs-cn/dev/how-to/migrat

[TiDB Lightning](/tidb-lightning/tidb-lightning-overview.md) 是一个用于将全量数据导入到 TiDB 集群的工具。

使用 TiDB Lightning 导入数据到 TiDB 时,有两种模式
使用 TiDB Lightning 导入数据到 TiDB 时,有三种模式

- `importer` 模式:以 TiKV-importer 作为后端,这种模式一般用于导入大量的数据(TB 级别)到新集群,但在数据导入过程中集群无法提供正常的服务。
- `tidb` 模式:以 TiDB/MySQL 作为后端,这种模式相比 `importer` 模式的导入速度较慢,但是可以在线导入,同时也支持将数据导入到 MySQL。
- `local` 模式:TiDB Lightning 将数据解析为有序的键值对,并直接将其导入 TiKV。这种模式一般用于导入大量的数据(TB 级别)到新集群,但在数据导入过程中集群无法提供正常的服务。
- `importer` 模式:和 `local` 模式类似,但是需要部署额外的组件 `tikv-importer` 协助完成键值对的导入。对于 4.0 以上的目标集群,请优先使用 `local` 模式进行导入。
- `tidb` 模式:以 TiDB/MySQL 作为后端,这种模式相比 `local``importer` 模式的导入速度较慢,但是可以在线导入,同时也支持将数据导入到 MySQL。

基本信息:

Expand All @@ -37,7 +38,7 @@ aliases: ['/docs-cn/dev/reference/tools/user-guide/','/docs-cn/dev/how-to/migrat

> **注意:**
>
> 原 Loader 工具已停止维护,不再推荐使用。相关场景请使用 TiDB Lightning 的 `tidb` 模式进行替代,详细信息请参考 [TiDB Lightning TiDB-backend 文档](/tidb-lightning/tidb-lightning-tidb-backend.md#从-loader-迁移到-tidb-lightning-tidb-backend)
> 原 Loader 工具已停止维护,不再推荐使用。相关场景请使用 TiDB Lightning 的 `tidb` 模式进行替代,详细信息请参考 [TiDB Lightning TiDB-backend 文档](/tidb-lightning/tidb-lightning-backends.md#从-loader-迁移到-tidb-lightning-tidb-backend)
## 备份和恢复

Expand Down
82 changes: 35 additions & 47 deletions get-started-with-tidb-lightning.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,14 +10,9 @@ TiDB Lightning 是一个将全量数据高速导入到 TiDB 集群的工具,
- **迅速**导入**大量新**数据。
- 备份恢复所有数据。

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 以上的内存
本教程假设使用的是若干新的、纯净版 CentOS 7 实例,你可以(使用 VMware、VirtualBox 及其他工具)在本地虚拟化或在供应商提供的平台上部署一台小型的云虚拟主机。因为 TiDB Lightning 对计算机资源消耗较高,建议分配 16 GB 以上的内存以及 32 核以上的 CPU 以获取最佳性能

> **警告:**
>
Expand Down Expand Up @@ -47,67 +42,60 @@ TiDB Lightning 主要包含两个部分:

### 第 1 步:部署 TiDB 集群

在开始数据导入之前,需先部署一套要进行导入的 TiDB 集群(版本要求 2.0.9 以上),本教程使用 TiDB 3.0.4 版本。部署方法可参考 [TiDB 部署方式](https://docs.pingcap.com/zh/tidb/v3.0/overview#部署方式)
在开始数据导入之前,需先部署一套要进行导入的 TiDB 集群(版本要求 2.0.9 以上),本教程使用 TiDB 4.0.3 版本。部署方法可参考 [TiDB 部署方式](https://docs.pingcap.com/zh/tidb/v3.0/overview#部署方式)

### 第 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 的服务器。
- **v4.0.3**: [tidb-toolkit-v4.0.3-linux-amd64.tar.gz](https://download.pingcap.org/tidb-toolkit-v4.0.3-linux-amd64.tar.gz)

2. 配置 `tikv-importer.toml`
### 第 3 步:启动 `tidb-lightning`

```toml
# TiKV Importer 配置文件模版
1. 将安装包里的 `bin/tidb-lightning``bin/tidb-lightning-ctl` 上传至部署 TiDB Lightning 的服务器。

# 日志文件。
log-file = "tikv-importer.log"
# 日志等级:trace、debug、info、warn、error、off。
log-level = "info"
2. 将数据源也上传到同样的服务器。

[server]
# tikv-importer 监听的地址,tidb-lightning 需要连到这个地址进行数据写入。
addr = "192.168.20.10:8287"
3. 配置 `tidb-lightning.toml`

[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 &
[lightning]
# 日志
level = "info"
file = "tidb-lightning.log"
[tikv-importer]
# 选择使用的 local 后端
backend = "local"
# 设置排序的键值对的临时存放地址,目标路径需要是一个空目录
"sorted-kv-dir" = "/mnt/ssd/sorted-kv-dir"
[mydumper]
# Mydumper 源数据目录。
data-source-dir = "/data/my_datasource/"
[tidb]
# 目标集群的信息
host = "172.16.31.2"
port = 4000
user = "root"
password = "rootroot"
# 表架构信息在从 TiDB 的“状态端口”获取。
status-port = 10080
# 集群 pd 的地址
pd-addr = "172.16.31.3:2379"
```
### 第 4 步:启动 `tidb-lightning`

1. 将安装包里的 `bin/tidb-lightning` 及 `bin/tidb-lightning-ctl` 上传至部署 TiDB Lightning 的服务器。

2. 将数据源也上传到同样的服务器。

3. 配置合适的参数运行 `tidb-lightning`。如果直接在命令行中用 `nohup` 启动程序,可能会因为 SIGHUP 信号而退出,建议把 `nohup` 放到脚本里面,如:
4. 配置合适的参数运行 `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-host 172.16.31.2 \
--tidb-user root \
--log-file tidb-lightning.log \
> nohup.out &
nohup ./tidb-lightning -config tidb-lightning.toml > nohup.out &
```
### 第 5 步:检查数据
### 第 4 步:检查数据
导入完毕后,TiDB Lightning 会自动退出。若导入成功,日志的最后一行会显示 `tidb lightning exit`。
Expand Down
2 changes: 1 addition & 1 deletion loader-overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ aliases: ['/docs-cn/dev/reference/tools/loader/','/docs-cn/tools/loader/','/docs

> **警告:**
>
> Loader 目前已经不再维护,其功能已经完全被 [TiDB Lightning 的 TiDB backend 功能](/tidb-lightning/tidb-lightning-tidb-backend.md)取代,强烈建议切换到 TiDB Lightning。
> Loader 目前已经不再维护,其功能已经完全被 [TiDB Lightning 的 TiDB backend 功能](/tidb-lightning/tidb-lightning-backends.md#tidb-lightning-tidb-backend)取代,强烈建议切换到 TiDB Lightning。
## Loader 简介

Expand Down
Binary file modified media/tidb-lightning-architecture.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
8 changes: 4 additions & 4 deletions migrate-from-mysql-mydumper-files.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,10 +12,10 @@ summary: 使用 TiDB Lightning 从 MySQL 迁移数据。
使用 Lightning 将数据导入 TiDB,Lightning 具体的部署方法见 [TiDB Lightning 部署](/tidb-lightning/deploy-tidb-lightning.md)

> **注意:**
>
> - 如果选用 Importer Backend 来导入数据,除需要部署 TiDB Lightning 组件外,也需要部署 TiKV Importer 组件。导入期间集群无法提供正常的服务,速度更快,适用于导入大量的数据(TB 以上级别)。
> - 如果选用 TiDB Backend 来导入数据,只需要部署 TiDB Lightning 组件。导入期间集群可以正常提供服务。
> - 二者的具体差别参见 [TiDB Lightning Backend](/tidb-lightning/tidb-lightning-tidb-backend.md)
>
> - 如果选用 Local Backend 来导入数据,导入期间集群无法提供正常的服务,速度更快,适用于导入大量的数据(TB 以上级别)。
> - 如果选用 TiDB Backend 来导入数据,导入期间集群可以正常提供服务, 但相对导入速度较慢
> - 二者的具体差别参见 [TiDB Lightning Backend](/tidb-lightning/tidb-lightning-backends.md)
## 第 2 步:配置 TiDB Lightning 的数据源

Expand Down
124 changes: 23 additions & 101 deletions tidb-lightning/deploy-tidb-lightning.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,9 @@ aliases: ['/docs-cn/dev/reference/tools/tidb-lightning/deployment/']

# TiDB Lightning 部署与执行

本文主要介绍 TiDB Lightning 使用 Importer-backend(默认)进行数据导入的硬件需求,以及使用 TiDB Ansible 部署与手动部署 TiDB Lightning 这两种部署方式。
本文主要介绍 TiDB Lightning 使用 Local-backend(默认)进行数据导入的硬件需求,以及使用 TiDB Ansible 部署与手动部署 TiDB Lightning 这两种部署方式。

如果你不希望影响 TiDB 集群的对外服务,可以参考 [TiDB Lightning TiDB-backend](/tidb-lightning/tidb-lightning-tidb-backend.md) 中的硬件需求与部署方式进行数据导入。
如果你不希望影响 TiDB 集群的对外服务,可以参考 [TiDB Lightning TiDB-backend](/tidb-lightning/tidb-lightning-backends.md#tidb-lightning-tidb-backend) 中的硬件需求与部署方式进行数据导入。

## 注意事项

Expand Down Expand Up @@ -38,33 +38,17 @@ aliases: ['/docs-cn/dev/reference/tools/tidb-lightning/deployment/']

## 硬件需求

`tidb-lightning``tikv-importer` 这两个组件皆为资源密集程序,建议各自单独部署。
`tidb-lightning`为资源密集程序,为了优化效能,建议硬件配置如下:

为了优化效能,建议硬件配置如下:

- `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`,然后将源数据以表为粒度进行切分,并发导入。
- 32+ 逻辑核 CPU
- 20GB+ 内存
- 足够储存整个数据源的 SSD 硬盘,读取速度越快越好
- 使用万兆网卡,带宽需要 1GB/s 以上
- 运行过程默认会占满 CPU,建议单独部署。条件不允许的情况下可以和其他组件(比如 `tikv-server`)部署在同一台机器上,然后通过配置 `region-concurrency` 限制 `tidb-lightning` 使用 CPU 资源。

> **注意:**
>
> - `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 集群必须有足够空间接收新导入的数据。除了[标准硬件配置](/hardware-and-software-requirements.md)以外,目标 TiKV 集群的总存储空间必须大于 **数据源大小 × [副本数量](/faq/deploy-and-maintain-faq.md#每个-region-的-replica-数量可配置吗调整的方法是) × 2**。例如集群默认使用 3 副本,那么总存储空间需为数据源大小的 6 倍以上。

Expand Down Expand Up @@ -96,30 +80,17 @@ aliases: ['/docs-cn/dev/reference/tools/tidb-lightning/deployment/']

TiDB Lightning 可随 TiDB 集群一起用 [TiDB Ansible 部署](/online-deployment-using-ansible.md)。

1. 编辑 `inventory.ini`分别配置一个 IP 来部署 `tidb-lightning` `tikv-importer`
1. 编辑 `inventory.ini``tidb-lightning` 配置一个 IP

```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
...
```
2. 修改 `group_vars/*.yml` 的变量配置 `tidb-lightning`

- `group_vars/lightning_server.yml`

Expand All @@ -134,16 +105,6 @@ TiDB Lightning 可随 TiDB 集群一起用 [TiDB Ansible 部署](/online-deploym
data_source_dir: "{{ deploy_dir }}/mydumper"
```

- `group_vars/importer_server.yml`

```yaml
---
dummy:
# 储存引擎文件的路径。需存放在空间足够大的分区。
import_dir: "{{ deploy_dir }}/data.import"
```

3. 开始部署。

{{< copyable "shell-regular" >}}
Expand All @@ -155,12 +116,14 @@ TiDB Lightning 可随 TiDB 集群一起用 [TiDB Ansible 部署](/online-deploym

4. 将数据源写入 `data_source_dir` 指定的路径。

5. 登录 `tikv-importer` 的服务器,并执行以下命令来启动 Importer。
5. 登录 `tidb-lightning` 的服务器,编辑 `conf/tidb-lighting.toml` 如下配置项:

{{< copyable "shell-regular" >}}

```sh
scripts/start_importer.sh
```
[tikv-importer]
# 选择使用 local 模式
backend = "local"
# 设置排序的键值对的临时存放地址,目标路径需要是一个空目录
"sorted-kv-dir" = "/mnt/ssd/sorted-kv-dir"
```

6. 登录 `tidb-lightning` 的服务器,并执行以下命令来启动 Lightning,开始导入过程。
Expand All @@ -171,8 +134,6 @@ TiDB Lightning 可随 TiDB 集群一起用 [TiDB Ansible 部署](/online-deploym
scripts/start_lightning.sh
```

7. 完成后,在 `tikv-importer` 的服务器执行 `scripts/stop_importer.sh` 来关闭 Importer。

### 手动部署 TiDB Lightning

#### 第 1 步:部署 TiDB 集群
Expand All @@ -183,54 +144,13 @@ TiDB Lightning 可随 TiDB 集群一起用 [TiDB Ansible 部署](/online-deploym

在[工具下载](/download-ecosystem-tools.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` 配置说明](/tidb-lightning/tidb-lightning-configuration.md#tikv-importer)。

3. 运行 `tikv-importer`

{{< copyable "shell-regular" >}}

```sh
nohup ./tikv-importer -C tikv-importer.toml > nohup.out &
```

#### 第 4 步:启动 `tidb-lightning`
#### 第 3 步:启动 `tidb-lightning`

1. 从安装包上传 `bin/tidb-lightning``bin/tidb-lightning-ctl`

2. 将数据源写入到同样的机器。

3. 配置 `tidb-lightning.toml`。对于没有出现在下述模版中的配置,TiDB Lightning 给出配置错误的提醒并退出。
3. 配置 `tidb-lightning.toml`。对于没有出现在下述模版中的配置,TiDB Lightning 给出配置错误的提醒并退出。`sorted-kv-dir`需要设置为一个空的目录,并且确保所在的磁盘有较多空闲的空间。

```toml
[lightning]
Expand All @@ -244,8 +164,10 @@ TiDB Lightning 可随 TiDB 集群一起用 [TiDB Ansible 部署](/online-deploym
file = "tidb-lightning.log"
[tikv-importer]
# tikv-importer 的监听地址,需改成 tikv-importer 服务器的实际地址。
addr = "172.16.31.10:8287"
# backend 设置为 local 模式
backend = "local"
# 设置本地临时存储路径
sorted-kv-dir = "/mnt/ssd/sorted-kv-dir"
[mydumper]
# Mydumper 源数据目录。
Expand Down
Loading

0 comments on commit 3a2891d

Please sign in to comment.