# [FAQ] Lightning 在 local-backend 模式并发导入同一张表的关键参数

## Key Words

Lightning, local-backend, 并发导入, incremental-import, pattern, checkpoint-remove

## Description

同一张表采用多个 Lightning Job 并行导入下游数据库的同一张的场景，参数配置项较多，容易忽略 3 个部分的参数细节：

Part.1 初始化 Lightning Job 并行导入配置；

Part.2 初始化 Lightning Job 断点续传配置;

Part.3 继续断点续传操作配置;

## Content

### Part.1 初始化 Lightning Job 并行导入配置

#### **1. `meta-schema-name` 采用默认配置**

无需需改 `lightning.meta-schema-name` 默认配置，该配置是将 Lightning job 导入的元信息以 task_id 命名的表存储在名为 “lightning_metadata“ 的 database 中。不需要做特殊配置。

```yaml
# 在并行导入模式下，在目标集群保存各个 TiDB Lightning 实例元信息的 schema 名字，默认为 "lightning_metadata"。
# 如果未开启并行导入模式，无须设置此配置项。
# **注意：**
# - 对于参与同一批并行导入的每个 TiDB Lightning 实例，该参数设置的值必须相同，否则将无法确保导入数据的正确性。
# - 如果开启并行导入模式，需要确保导入使用的用户（对于 tidb.user 配置项）有权限创建和访问此配置对应的库。
# - TiDB Lightning 在导入完成后会删除此 schema，因此不要使用已存在的库名配置该参数。
meta-schema-name = "lightning_metadata"
```

#### **2. `tikv-importer.incremental-import` 必须配置**

在 Lightning v5.3.1 及以后版本每一个 Lightning job 必须配置，才能保证多个 Lighting job 并行导入同一张被关联起来，以保证断点续传和并行导入任务的成功。

```yaml
[tikv-importer]
# "local"：Physical Import Mode，默认使用。适用于 TB 级以上大数据量，但导入期间下游 TiDB 无法对外提供服务。
# "tidb"：Logical Import Mode。TB 级以下数据量可以采用，下游 TiDB 可正常提供服务。
# backend = "local"
# 是否允许向已存在数据的表导入数据。默认值为 false。
# 当使用并行导入模式时，由于多个 TiDB Lightning 实例同时导入一张表，因此此开关必须设置为 true。
incremental-import = true
```

#### **3. `mydumper.files.pattern` 不同 Lightning Job 单独配置避免重复导入**

因为是同一张表并行导入到下游目标表，通过 pattern 将导入数据文件分散到不同 Lightning Job，注意不同的 Lightning Job 之间的 .sql 或者 .csv 文件名不能有重复，否则会报错。

```yaml
[[mydumper.files]]
# 解析 AWS Aurora parquet 文件所需的表达式
pattern = '(?i)^(?:[^/]*/)*([a-z0-9_]+)\.([a-z0-9_]+)/(?:[^/]*/)*(?:[a-z0-9\-_.]+\.(parquet))$'
schema = '$1'
table = '$2'
type = '$3'
```

#### **正则表达式数字如何写正确**

##### **反例一：Job 之间交集，数字重复**

```markdown
# 交集: 0000[0-9]00000 的文件名，所以两个 Job1 和 Job2 的导入文件冲突了，Lightning 导入 Job 会失败报错。

Lightning job 1 pattern = '(?i)^(?:[^/]*/)*data\.data_partition\.(0000[0-9][0-9]0000)\.csv'

Lihgtning job 2 pattern = '(?i)^(?:[^/]*/)*data\.data_partition\.(000[0-9][0-9]00000)\.csv'
```

##### **反例二：JOb 之间不交集，数字缝隙**

```markdown
# 缝隙：漏掉 0000[6-9][0-5]0000,0000[0-5][6-9]0000,0000[6-9][0-5]0000,0000[0-5][6-9]0000 的文件名，导入数据缺失

Lightning job 1 pattern = '(?i)^(?:[^/]*/)*data\.data_partition\.(0000[0-5][0-5]0000)\.csv'

Lihgtning job 2 pattern = '(?i)^(?:[^/]*/)*data\.data_partition\.(0000[6-9][6-9]0000)\.csv'
```

##### **正例： Job 之间不交集，数字连续**

```markdown
# 解释：Job 1 的数字范围是 0000000000 到 0005990000，既是 600 个文件名， Job 2 的数字范围是 0006000000 到 0009990000，既是 400 个文件名。

Lightning job 1 pattern = '(?i)^(?:[^/]*/)*data\.data_partition\.(000000[0-5][0-9][0-9]0000)\.csv'

Lihgtning job 2 pattern = '(?i)^(?:[^/]*/)*data\.data_partition\.(000000[6-9][0-9][0-9]0000)\.csv'
```

### Part.2 初始化 Lightning Job 断点续传配置

#### **`checkpoint.schema` 不同 Lightning Job 单独配置**

不同的 Lighting Job 需要配置不同的 checkpoint.schema， 由于导入同一个下游集群，所以 Job 的导入进度需要单独报错，不能冲突。

```yaml
[checkpoint]
# 是否启用断点续传。
# 导入数据时，TiDB Lightning 会记录当前表导入的进度。
# 所以即使 TiDB Lightning 或其他组件异常退出，在重启时也可以避免重复再导入已完成的数据。
enable = true
# 存储断点的数据库名称。
schema = "tidb_lightning_checkpoint"
```

### Part.3 继续断点续传操作配置

#### **`checkpoint-remove` 注意执行成功的结果输出和反引号的使用**

1. 在执行 `checkpoint-remove` 操作时，会在下游的数据库中执行命令 `delete` from xxxx where tbl_name=`data`.`data_paratition` 时，

    只有返回的 **`1 row deleted`** 才证明该**操作成功**。

2. 当使用 `checkpoint-remove` 命令进行恢复断点续传时，一定注意`反引号`的使用。容易出现情况的反引号缺失，造成执行失败，**不会返回报错输出**。

    ```markdown
    # 删除 checkpoint 时需要使用 `quoted identifier`，将 schema 和 table 分别用反引号区分 
    
    ## 正确例子
    
    {{--checkpoint-remove='`data`.`data_partition`'}}
    
    ## 错误例子，这样写会无法识别
    
    {{--checkpoint-remove='data.data_partition'}})
    ```

## Affected Versions

All of version

## Reference

[官方文档的 TiDB Lightning 任务配置](https://docs.pingcap.com/zh/tidb/v6.3/tidb-lightning-configuration#tidb-lightning-%E4%BB%BB%E5%8A%A1%E9%85%8D%E7%BD%AE)