Skip to content

Commit

Permalink
tidb-lightning: update docs (pingcap#4094)
Browse files Browse the repository at this point in the history
* tidb-lightning: update docs

* Update migrate-from-csv-using-tidb-lightning.md

* Update tidb-lightning-configuration.md

* Update tidb-lightning-configuration.md

* Update migrate-from-csv-using-tidb-lightning.md

* Apply suggestions from code review

Co-authored-by: kennytm <kennytm@gmail.com>

* Update troubleshoot-tidb-lightning.md

* Update tidb-lightning-configuration.md

* Update tidb-lightning-configuration.md

* Update migrate-from-csv-using-tidb-lightning.md

* update expression

* Apply suggestions from code review

Co-authored-by: kennytm <kennytm@gmail.com>

* Apply suggestions from code review

Co-authored-by: TomShawn <41534398+TomShawn@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: TomShawn <41534398+TomShawn@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: TomShawn <41534398+TomShawn@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: TomShawn <41534398+TomShawn@users.noreply.github.com>

* Apply suggestions from code review

* add back changes

Co-authored-by: kennytm <kennytm@gmail.com>
Co-authored-by: TomShawn <41534398+TomShawn@users.noreply.github.com>
  • Loading branch information
3 people authored Aug 3, 2020
1 parent f9956b0 commit 8bc72fd
Show file tree
Hide file tree
Showing 8 changed files with 126 additions and 13 deletions.
2 changes: 1 addition & 1 deletion tidb-lightning/deploy-tidb-lightning.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ aliases: ['/docs-cn/dev/reference/tools/tidb-lightning/deployment/']
{{< copyable "shell-regular" >}}

```sh
bin/tidb-lightning-ctl -switch-mode=normal
bin/tidb-lightning-ctl --switch-mode=normal
```

- TiDB Lightning 需要下游 TiDB 有如下权限:
Expand Down
21 changes: 20 additions & 1 deletion tidb-lightning/migrate-from-csv-using-tidb-lightning.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,15 @@ TiDB Lightning 支持读取 CSV(逗号分隔值)的数据源,以及其他
包含整张表的 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`
* 创建包含 DDL 语句 `CREATE TABLE` 的文件 `db_name.table_name-schema.sql` 以及包含 `CREATE DATABASE` DDL 语句的文件 `db_name-schema-create.sql`
* 首先在 TiDB 中直接创建空表,然后在 `tidb-lightning.toml` 中设置 `[mydumper] no-schema = true`

## 配置
Expand Down Expand Up @@ -136,6 +137,24 @@ TiDB Lightning 并不完全支持 `LOAD DATA` 语句中的所有配置项。例
* 不可跳过表头(`IGNORE n LINES`)。如有表头,必须是有效的列名。
* 定界符和分隔符只能为单个 ASCII 字符。
## 设置 `strict-format` 启用严格格式
导入文件的大小统一约为 256 MB 时,TiDB Lightning 可达到最佳工作状态。如果导入单个 CSV 大文件,TiDB Lightning 只能使用一个线程来处理,这会降低导入速度。
要解决此问题,可先将 CSV 文件分割为多个文件。对于通用格式的 CSV 文件,在没有读取整个文件的情况下无法快速确定行的开始和结束位置。因此,默认情况下 TiDB Lightning 不会自动分割 CSV 文件。但如果你确定待导入的 CSV 文件符合特定的限制要求,则可以启用 `strict-format` 设置。启用后,TiDB Lightning 会将单个 CSV 大文件分割为单个大小为 256 MB 的多个文件块进行并行处理。
```toml
[mydumper]
strict-format = true
```

严格格式的 CSV 文件中,每个字段仅占一行,即必须满足以下条件之一:

* 分隔符为空;
* 每个字段不包含 CR (`\r`)或 LF(`\n`)。

如果 CSV 文件不是严格格式但 `strict-format` 被误设为 `true`,跨多行的单个完整字段会被分割成两部分,导致解析失败,甚至不报错地导入已损坏的数据。

## 通用配置

### CSV
Expand Down
16 changes: 13 additions & 3 deletions tidb-lightning/monitor-tidb-lightning.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ aliases: ['/docs-cn/dev/reference/tools/tidb-lightning/monitor/']
- 如果是使用 TiDB Ansible 部署 Lightning,只要将服务器地址加到 `inventory.ini` 文件里的 `[monitored_servers]` 部分即可。
- 如果是手动部署 Lightning,则参照以下步骤进行配置。

只要 Prometheus 能发现 `tidb-lightning` 的监控地址,就能收集监控指标
只要 Prometheus 能发现 `tidb-lightning` `tikv-importer` 的监控地址,就能收集对应的监控指标

监控的端口可在 `tidb-lightning.toml` 中配置:

Expand All @@ -24,16 +24,26 @@ pprof-port = 8289
...
```

要让 Prometheus 发现 Lightning,可以将地址直接写入其配置文件,例如:
监控的端口也可在 `tikv-importer.toml` 配置:

```toml
# 状态服务器的监听地址
status-server-address = '0.0.0.0:8286'
```

配置 Prometheus 后,`tidb-lightning` 才能发现服务器。配置方法如下,将服务器地址直接添加至 `scrape_configs` 部分:

{{< copyable "" >}}

```yaml
...
scrape_configs:
- job_name: 'tidb-lightning'
- job_name: 'lightning'
static_configs:
- targets: ['192.168.20.10:8289']
- job_name: 'tikv-importer
static_configs:
- targets: ['192.168.20.9:8286']
```
## Grafana 面板
Expand Down
5 changes: 4 additions & 1 deletion tidb-lightning/tidb-lightning-backends.md
Original file line number Diff line number Diff line change
Expand Up @@ -388,9 +388,12 @@ TiDB Lightning 可随 TiDB 集群一起用 [TiDB Ansible 部署](/online-deploym
# 日志等级:trace、debug、info、warn、error、off。
log-level = "info"

# 状态服务器的监听地址。
status-server-address = "0.0.0.0:8286"

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

[metric]
# 给 Prometheus 客户端的推送任务名称。
Expand Down
68 changes: 64 additions & 4 deletions tidb-lightning/tidb-lightning-configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,15 @@ table-concurrency = 6
# 对于不同的存储介质,此参数可能需要调整以达到最佳效率。
io-concurrency = 5

[security]
# 指定集群中用于 TLS 连接的证书和密钥。
# CA 的公钥证书。如果留空,则禁用 TLS。
# ca-path = "/path/to/ca.pem"
# 此服务的公钥证书。
# cert-path = "/path/to/lightning.pem"
# 该服务的密钥。
# key-path = "/path/to/lightning.key"

[checkpoint]
# 是否启用断点续传。
# 导入数据时,TiDB Lightning 会记录当前表导入的进度。
Expand Down Expand Up @@ -121,7 +130,7 @@ batch-import-ratio = 0.75

# mydumper 本地源数据目录。
data-source-dir = "/data/my_database"
# 如果 no-shcema = true,那么 TiDB Lightning 假设目标 TiDB 集群上
# 如果 no-schema = true,那么 TiDB Lightning 假设目标 TiDB 集群上
# 已有表结构,并且不会执行 `CREATE TABLE` 语句。
no-schema = false
# 指定包含 `CREATE TABLE` 语句的表结构文件的字符集。只支持下列选项:
Expand All @@ -132,6 +141,18 @@ no-schema = false
# 注意:**数据** 文件始终解析为 binary 文件。
character-set = "auto"

# “严格”格式的导入数据可加快处理速度。
# strict-format = true 要求:
# 在 CSV 文件的所有记录中,每条数据记录的值不可包含字符换行符(U+000A 和 U+000D,即 \r 和 \n)
# 甚至被引号包裹的字符换行符都不可包含,即换行符只可用来分隔行。
# 导入数据源为严格格式时,TiDB Lightning 会快速定位大文件的分割位置进行并行处理。
# 但是如果输入数据为非严格格式,可能会将一条完整的数据分割成两部分,导致结果出错。
# 为保证数据安全而非追求处理速度,默认值为 false。
strict-format = false

# 如果 strict-format = true,TiDB Lightning 会将 CSV 大文件分割为多个文件块进行并行处理。max-region-size 是分割后每个文件块的最大大小。
# max-region-size = 268_435_456 # Byte(默认是 256 MB)

# 只导入与该通配符规则相匹配的表。详情见相应章节。
filter = ['*.*']

Expand Down Expand Up @@ -176,12 +197,29 @@ index-serial-scan-concurrency = 20
checksum-table-concurrency = 16

# 解析和执行 SQL 语句的默认 SQL 模式。
sql-mode = "STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION"
sql-mode = "ONLY_FULL_GROUP_BY,NO_ENGINE_SUBSTITUTION"
# `max-allowed-packet` 设置数据库连接允许的最大数据包大小,
# 对应于系统参数中的 `max_allowed_packet`。 如果设置为 0,
# 会使用下游数据库 global 级别的 `max_allowed_packet`。
max-allowed-packet = 67_108_864

# SQL 连接是否使用 TLS。可选值为:
# * "" - 如果填充了 [tidb.security] 部分,则强制使用 TLS(与 "cluster" 情况相同),否则与 "false" 情况相同
# * "false" - 禁用 TLS
# * "cluster" - 强制使用 TLS 并使用 [tidb.security] 部分中指定的 CA 验证服务器的证书
# * "skip-verify" - 强制使用 TLS,但不验证服务器的证书(不安全!)
# * "preferred" - 与 "skip-verify" 相同,但是如果服务器不支持 TLS,则会退回到未加密的连接
# tls = ""
# 指定证书和密钥用于 TLS 连接 MySQL。
# 默认为 [security] 部分的副本。
# [tidb.security]
# CA 的公钥证书。设置为空字符串可禁用 SQL 的 TLS。
# ca-path = "/path/to/ca.pem"
# 该服务的公钥证书。默认为 `security.cert-path` 的副本
# cert-path = "/path/to/lightning.pem"
# 此服务的私钥。默认为 `security.key-path` 的副本
# key-path = "/path/to/lightning.key"

# 数据导入完成后,tidb-lightning 可以自动执行 Checksum、Compact 和 Analyze 操作。
# 在生产环境中,建议这将些参数都设为 true。
# 执行的顺序为:Checksum -> Compact -> Analyze。
Expand Down Expand Up @@ -217,13 +255,18 @@ log-file = "tikv-importer.log"
# 日志等级:trace, debug, info, warn, error 和 off
log-level = "info"

# 状态服务器的监听地址。
# Prometheus 可以从这个地址抓取监控指标。
status-server-address = "0.0.0.0:8286"

[server]
# tikv-importer 的监听地址,tidb-lightning 需要连到这个地址进行数据写入。
addr = "192.168.20.10:8287"
addr = "0.0.0.0:8287"
# gRPC 服务器的线程池大小。
grpc-concurrency = 16

[metric]
# 当使用 Prometheus Pushgateway 时会涉及相关设置。通常可以通过 Prometheus 从 状态服务器地址中抓取指标。
# 给 Prometheus 客户端推送的 job 名称。
job = "tikv-importer"
# 给 Prometheus 客户端推送的间隔。
Expand Down Expand Up @@ -251,6 +294,12 @@ compression-per-level = ["lz4", "no", "no", "no", "no", "no", "lz4"]
# 同上
compression-per-level = ["lz4", "no", "no", "no", "no", "no", "lz4"]

[security]
# TLS 证书的路径。空字符串表示禁用安全连接。
# ca-path = ""
# cert-path = ""
# key-path = ""

[import]
# 存储引擎文件的文件夹路径
import-dir = "/mnt/ssd/data.import/"
Expand Down Expand Up @@ -289,7 +338,7 @@ min-available-ratio = 0.05
| -L *level* | 日志的等级: debug、info、warn、error 或 fatal (默认为 info) | `lightning.log-level` |
| -f *rule* | [表库过滤的规则](/table-filter.md) (可多次指定) | `mydumper.filter` |
| --backend [*backend*](/tidb-lightning/tidb-lightning-backends.md) | 选择后端的模式:`importer``local``tidb` | `tikv-importer.backend` |
| --log-file *file* | 日志文件路径 | `lightning.log-file` |
| --log-file *file* | 日志文件路径(默认是 `/tmp` 中的临时文件) | `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` |
Expand All @@ -298,6 +347,15 @@ min-available-ratio = 0.05
| --tidb-status *port* | TiDB Server 的状态端口的(默认为 10080) | `tidb.status-port` |
| --tidb-user *user* | 连接到 TiDB 的用户名 | `tidb.user` |
| --tidb-password *password* | 连接到 TiDB 的密码 | `tidb.password` |
| --no-schema | 忽略表结构文件,直接从 TiDB 中获取表结构信息 | `mydumper.no-schema` |
| --enable-checkpoint *bool* | 是否启用断点 (默认值为 true) | `checkpoint.enable` |
| --analyze *bool* | 导入后分析表信息 (默认值为 true) | `post-restore.analyze` |
| --checksum *bool* | 导入后比较校验和 (默认值为 true) | `post-restore.checksum` |
| --check-requirements *bool* | 开始之前检查集群版本兼容性(默认值为 true)| `lightning.check-requirements` |
| --ca *file* | TLS 连接的 CA 证书路径 | `security.ca-path` |
| --cert *file* | TLS 连接的证书路径 | `security.cert-path` |
| --key *file* | TLS 连接的私钥路径 | `security.key-path` |
| --server-mode | 在服务器模式下启动 TiDB Lightning | `lightning.server-mode` |

如果同时对命令行参数和配置文件中的对应参数进行更改,命令行参数将优先生效。例如,在 `cfg.toml` 文件中,不管对日志等级做出什么修改,运行 `./tidb-lightning -L debug --config cfg.toml` 命令总是将日志级别设置为 “debug”。

Expand All @@ -309,6 +367,7 @@ min-available-ratio = 0.05
|:----|:----------|
| --compact | 执行 full compact |
| --switch-mode *mode* | 将每个 TiKV Store 切换到指定模式(normal 或 import) |
| --fetch-mode | 打印每个 TiKV Store 的当前模式 |
| --import-engine *uuid* | 将 TiKV Importer 上关闭的引擎文件导入到 TiKV 集群 |
| --cleanup-engine *uuid* | 删除 TiKV Importer 上的引擎文件 |
| --checkpoint-dump *folder* | 将当前的断点以 CSV 格式存储到文件夹中 |
Expand All @@ -329,6 +388,7 @@ min-available-ratio = 0.05
| -C, --config *file* |*file* 读取配置。如果没有指定,则使用默认设置| |
| -V, --version | 输出程序的版本 | |
| -A, --addr *ip:port* | TiKV Importer 服务器的监听地址 | `server.addr` |
| --status-server *ip:port* | 状态服务器的监听地址 | `status-server-address` |
| --import-dir *dir* | 引擎文件的存储目录 | `import.import-dir` |
| --log-level *level* | 日志的等级: trace、debug、info、warn、error 或 off | `log-level` |
| --log-file *file* | 日志文件路径 | `log-file` |
10 changes: 9 additions & 1 deletion tidb-lightning/tidb-lightning-faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -141,7 +141,15 @@ sql-mode = ""

## 为什么用过 TiDB Lightning 之后,TiDB 集群变得又慢又耗 CPU?

如果 `tidb-lightning` 曾经异常退出,集群可能仍留在“导入模式” (import mode),不适合在生产环境工作。此时需要强制切换回“普通模式” (normal mode):
如果 `tidb-lightning` 异常退出,集群可能仍处于“导入模式” (import mode),该模式不适用于生产环境。此时可执行以下命令查看当前使用的模式:

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

```sh
tidb-lightning-ctl --fetch-mode
```

可执行以下命令强制切换回“普通模式” (normal mode):

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

Expand Down
4 changes: 3 additions & 1 deletion tidb-lightning/tidb-lightning-glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,9 @@ TiDB Lightning 通过比较每个表的[本地校验和](#local-checksum)和[远

### Chunk

指数据源中的单个文件。
一段连续的源数据,通常相当于数据源中的单个文件。

如果单个文件太大,TiDB Lightning 可以将单个文件拆分成多个文件块。

### Compaction

Expand Down
13 changes: 12 additions & 1 deletion troubleshoot-tidb-lightning.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,18 @@ TiDB Lightning 的正常速度为每条线程每 2 分钟导入一个 256 MB 的

每条索引都会额外增加键值对。如果有 N 条索引,实际导入的大小就差不多是 Mydumper 文件的 N+1 倍。如果索引不太重要,可以考虑先从 schema 去掉,待导入完成后再使用 `CREATE INDEX` 加回去。

**原因 3**:Lightning 版本太旧。
**原因 3**: 单个文件过大。

把源数据分割为单个大小约为 256 MB 的多个文件时,TiDB Lightning 会并行处理数据,达到最佳效果。如果导入的单个文件过大,TiDB Lightning 可能无响应。

如果源数据是 CSV 格式文件,并且所有的 CSV 文件内都不存在包含字符换行符的字段 (U+000A 及 U+000D),则可以启用 `strict-format`,TiDB Lightning 会自动分割大文件。

```toml
[mydumper]
strict-format = true
```

**原因 4**:TiDB Lightning 版本太旧。

试试最新的版本吧!可能会有改善。

Expand Down

0 comments on commit 8bc72fd

Please sign in to comment.