本文档介绍了 MatrixGate 的详细参数信息。
注意！
此部分的参数为 mxgate 启动前生成的配置文件中的参数。
| 参数名 | 默认值 | 描述 |
|---|---|---|
| [database]类别 | ||
| --db-database | postgres | MatrixGate 连接 YMatrix 数据库名 |
| --db-master-host | 本机主机名 | MatrixGate 连接 YMatrix 主机名 |
| --db-master-port | 5432 | MatrixGate 连接 YMatrix 主机端口号 |
| --db-user | 当前系统用户名 | MatrixGate 连接 YMatrix 用户名 注意！ 该用户必须具有创建外部表的权限，如果使用的是非超级权限用户，请使用如下命令增加权限： alter user {username} CREATEEXTTABLE; |
| --db-password | 空 | MatrixGate 连接 YMatrix 用户密码 |
| --db-max-conn | 10 | MatrixGate 连接 YMatrix 最大连接数 |
| [job]类别 | ||
| --allow-dynamic | false | 当指定 --allow-dynamic=true 时，允许根据 POST 的数据内容(第一行)，动态适配插入的目标表。此选项应仅用于 MatrixGate 启动时目标表名尚未确定的场景。如果固定插入某个已知的目标表，推荐用 --target 显式指定表名 |
| --delimiter | | | 指定用于分隔文件每一行（行）中各列的字符 |
| --error-handling | accurate | 遇到格式错误行的处理方式'accurate'：错误数据不入库并记录错误日志，该批次其他数据不受影响'legacy'：该批次整体失败 |
| --exclude-columns | 空 | 数据加载默认提供的列数量和列顺序需要与表定义一致，当数据加载仅提供部分列时，--exclude-columns 用于标记排除的列名，其他列仍需要保证顺序与表定义一致。 提示：如果已经开启 --use-auto-increment 跳过自增字段，则不需要在此列出这些自增字段。这个参数只需要标记出其他还需要排除的列名即可 |
| --format | text | 指定源数据的数据格式 text 或 csv。text 速度最快，但不支持字符类型中出现换行。csv 格式适用性更广，对字符类型的列必须用双引号 |
| --null-as | 空字符串 | 指定表示空值的字符串。 默认值为无引号的空字符串。当数据表中的列约束为非空 NOT NULL，且数据内容上该列给出了空值，将会导致加载报错。提示：如需要使用 \N 为空值，需要对反斜杠进行转义，如：--null-as \N |
| --time-format | unix-second | 指定时间戳单位：unix-second、unix-ms、unix-nano 或 raw。\n MatrixGate默认将每行数据的第一列当作时间戳的 Unix 表示，自动将其转化为数据库时间格式。如果时间戳不在第一列，或者用户已经自行转换为数据库格式，则应使用 raw，这样 MatrixGate 不会做时间类型转换 |
| --upsert-key | 空 | 进行 UPSERT 的键名，可以指定多个。需要做 UPSERT 的表，必须建立 UNIQUE 约束，且参数中要指定所有约束键 |
| --deduplicate-key | 空 | 用法和 UPSERT 类似，区别是只更新空值，如果旧值非空，新值丢弃。和 --upsert-key 参数互斥，只能选一种 |
| --use-auto-increment | true | 当 target 表中含有自增字段时，是否在加载数据中跳过自增字段赋值而使用系统默认自增值 |
| --target | schemaName.tableName | 指定目标的表名，schemaName 可以省略，默认为 public。允许指定多个目标表，使用方法是 "--target 表1 --target 表2 …"。当不提供此参数时，可以额外指定 --allow-dynamic 参数来允许动态适配表名 |
| --dml-template | 将 JSON 字段映射到元组列（Tuple Column）的映射模板的文件路径 | |
| [misc]类别 | ||
| --log-archive-hours | 72 | 日志目录下，超过一定时间未发生改变的 MatrixGate 日志文件，被自动压缩 |
| --log-compress | true | 是否开启 log 自动压缩的全局开关 |
| --log-dir | /home/mxadmin/gpAdminLogs | 日志目录 |
| --log-max-archive-files | 0 | 最多保留多少个压缩的 log 文件，超过这个数量，则最老的日志文件会被删除。0 为不删除 |
| --log-remove-after-days | 0 | 被压缩后的 log 文件，再经过多少天被自动删除。0 为不删除 |
| --log-rotate-size-mb | 100 | 当前 log 文件超过一定大小则自动切换到一个新文件，旧文件则立即压缩 |
| -v / --verbose | 打印详细的 verbose 日志 | |
| -V / --debug | 打印详细的调试日志（包含 verbose 日志及 debug 日志） | |
| --pprof-port | 访问 Pprof 信息的端口，0 表示禁用 |
|
| --no-cleanup | 即使在正常退出时也保留临时模式 | |
| --grpc-port | 访问 gRPC 信息的端口，0 表示禁用 |
|
| [metrics]类别 | ||
| --metrics-enable | true | 启用指标 |
| --metrics-sample-interval | 15(从 v5.3.2 调整为 15，之前为 3) | 指标的采样间隔（秒）。将其设置为 >0 以启用指标收集（会降低性能） |
| [source]类别 | ||
| --source | http | MatrixGate 数据来源，支持 http / stdin / kafka / transfer / grpc |
| [source]类别 | [HTTP] | 注意：此模式为配置文件中的默认数据源连接模式 |
| --http-port | 8086 | MatrixGate 用户提交数据的 HTTP 接口 |
| --max-body-bytes | 4194304 | 每个 HTTP 包体大小上限 |
| --max-concurrency | 40000 | HTTP 最大并发连接数 |
| --request-timeout | 0 | 请求超时时间，默认 0。当设置大于 0 的值，会在等待毫秒单位的设置时间后超时并返回 timeout(408) |
| --disable-keep-alive | false | MatrixGate 在每次 HTTP 请求后强制断开连接 |
| --http-debug | false | 输出附加 HTTP 源的诊断信息 |
| [source]类别 | [Transfer] | 注意：迁移模式非默认模式，如需使用此模式，请手动配置此部分参数 |
| --src-host | 源库 Master 的 IP 地址 | |
| --src-port | 源库 Master 的端口号 | |
| --src-user | 连接源库的用户名(建议使用 Superuser) |
|
| --src-password | 连接密码 | |
| --src-schema | 源表的模式名 | |
| --src-table | 源表的表名 | |
| --src-sql | 进行迁移数据过滤的 SQL | |
| --compress | 数据从源数据库 Segment 传输到本数据库的压缩方法： 空白字符串“”，代表不压缩，明文传输 gzip：使用 gzip 压缩，需要源数据库的 Segment 主机上必须安装有 gzip 这个 Linux 命令lz4：使用 lz4 压缩，需要源数据库的 Segment 主机上必须安装有 lz4 这个 Linux 命令推荐 lz4 > gzip > 不压缩 |
|
| --port-base | 9129 | 传输中会占用一个端口 |
| --local-ip | 必须用源库可以连接到本机的 IP 地址 | |
| [source]类别 | [Kafka] | 注意：此模式非默认模式，如需使用此模式，请手动配置此部分参数；完整认证示例见 Kafka 加密连接 |
| --kafka-broker | 无 | Kafka broker 地址，多个 broker 用逗号分隔 |
| --kafka-version | 1_0_0_0 | Kafka 版本。可选值：0_8_2_0、0_8_2_1、0_8_2_2、0_9_0_0、0_9_0_1、0_10_0_0、0_10_0_1、0_10_1_0、0_10_1_1、0_10_2_0、0_10_2_1、0_11_0_0、0_11_0_1、0_11_0_2、1_0_0_0、1_1_0_0、2_0_0_0 |
| --kafka-lib-log | false | 是否输出 Kafka 连接过程的日志 |
| --kafka-max-checkpoint-gap | 134217728 | 消费 checkpoint 与已消费 offset 之间允许的最大间隔（字节） |
| --kafka-message-count | 0 | 需要消费的消息数量，0 表示不限制 |
| --kafka-params | 空 | 以字符串形式给出 topic、partition、consumer-group、consumer-group-members 和 job；使用 [[source.kafka.topic]] 时可省略 |
| --enable-sasl | false | 是否启用 SASL 认证 |
| --enable-sasl-handshake | false | 是否启用 Kafka SASL handshake，标准 Kafka SASL 连接一般设为 true |
| --sasl-mechanism --sasl-user --sasl-password |
空 | SASL 认证机制与认证信息 |
| --scram-algorithm --scram-authz-id |
空 | SCRAM 认证使用的算法与授权 ID |
| --ssl-ca-cert | 空 | CA 证书路径；配置该参数后启用 SSL 连接 |
| --gssapi-auth-type | 空 | GSSAPI 认证方式：KEYTAB 表示使用 keytab 文件认证，USER 表示使用用户名密码认证 |
| --gssapi-kerberos-config-path --gssapi-keytab-path --gssapi-user --gssapi-password --gssapi-realm --gssapi-service-name |
空 | GSSAPI 认证所需的配置路径与身份信息，示例见 Kafka 加密连接 |
| --gssapi-disable-pafxfast | false | 是否关闭 GSSAPI 快速认证（PAFXFAST）；连接在快速认证阶段失败时设为 true 后重试 |
| [source]类别 | [[source.kafka.topic]] |
注意：每个 topic 一条；同一 topic 可配置多个消费成员 |
| --topic | 无 | 需要消费的 Kafka 主题 |
| --partition | 无 | 需要消费的分区，* 表示全部分区 |
| --job | 无 | 该 topic 对应的写入任务（Job）名称 |
| --consumer-group | 空 | 该 topic 使用的消费组；不配置时不使用消费组 |
| --consumer-group-members | — | 该 topic 的消费成员数；配置多个成员时，由同一消费组内的多个成员共同消费该 topic |
| [transform]类别 | ||
| --transform | plain | 将写入的数据进行格式或类型转换。支持 plain / json / nil / tsbs / hanagdbc |
| [writer]类别 | ||
| --interval | 100 毫秒 | MatrixGate 执行批量数据加载时间周期 |
| --writer | stream | MatrixGate 通过 Writer 将数据写入到 YMatrix。支持 stream / nil |
--stream-prepared |
10 | 在一个任务（Job）中同时调用几个 slot 进程 |
| --stream-host | mdw | YMatrix 中 Master 连接到 MatrixGate 的主机名。这是为了系统有多个网络接口 |
| --use-gzip | auto | MatrixGate 向 Segment 发送数据时是否开启压缩，可配置参数为 auto/yes/no：auto 设置下优先选用 zstd 压缩算法；设为 --use-gzip=yes 意味着使用 gzip 压缩算法设为 --use-gzip=no，则会禁止压缩传输。此设置虽能节省少量 CPU 占用，但是会大大增加网络传输数据量，我们建议除非为单机部署的数据库，且 mxgate 和数据库全部在同一台主机上，否则慎用 no 设置，一律采用默认值 auto 即可 |
| --max-seg-conn | 128 | 外部表从 MatrixGate 拉取数据时启动的 Segment 数量，调大该参数会增加网络连接资源 |
| --timing | false | 将该参数设置为 true 后，MatrixGate 在记录日志时会为每条 INSERT 增加耗时信息 |
| --insert-timeout | 600000 | MatrixGate 执行 INSERT 语句超时时间。设置大于 0 的值后会在等待毫秒单位配置时间后超时 |
| -I / --instrumentation | disable | 打开 slot(s) 的检测，支持 disable / single / all 选项：disable 表示禁用此功能；single 表示只打开 slot[0] 的检测；all 表示打开所有 slot 的检测 |
--bytes-limit |
批量数据加载的的大小限制。在输入到 MatrixGate 的数据流不均匀的情况下，保障入库数据均匀。此功能默认不启用，若启用需要手动配置大小，取值范围为 0~INT_MAX |
|
--auto-tune |
false | 将该参数设置为 true 后，MatrixGate 可以调整写入任务的 slot 数 |
--abort-by-pause-timeout |
10000 | 在任务（Job）被执行暂停（Pause）命令后， 一旦达到该参数中所指定的超时时间，则自动放弃内存堆积的将要写入到数据库的数据。此参数取值范围为 0~INT_MAX；推荐取值 1000~10000，单位为毫秒（ms）；如果设置为 0，则禁用此功能。建议配置此值明显低于 --request-timeout，以保证任务未处于暂停状态时，仍然使用 --request-timeout 为超时时间。一旦任务被暂停，mxgate 就会自动比对以上所述两个超时参数，并依照其中较低的值触发超时报错。该参数只有在 writer="stream" 时才可配置 |
注意！
此部分参数为 mxgate 启动后可在命令行中运行的参数。
| 参数名 | 子参数名 | 描述 |
| run | 在命令行运行 MatrixGate | |
| start | 启动 MatrixGate 后台进程 | |
| stop | 终止 MatrixGate 后台进程 | |
| -f / --force | 强制终止 MatrixGate 进程 | |
| --grpc-port | 通过发送 gRPC 请求终止正在监听指定端口的 MatrixGate 进程 | |
| status | 打印 MatrixGate 后台进程的状态 | |
| config | 打印完整的配置文件 | |
| log | 显示最新的 10 条日志 | |
| -n / --lines int | 指定显示最新的多少条日志，不可以省略后跟 int 参数 | |
| version | 显示版本 | |
| help | 显示用法和参数列表 | |
| -C / --config | 加载配置文件，目前支持作为 start / run 的子参数运行 | |
| -p / --pid | MatrixGate 进程的 ID，目前支持作为 stop / log / watch / pause / resume 的子参数运行 | |
| --job | 需要设置参数的任务（Job）。由于每个 Job 都存在于一个表中，因此实际应用中指定相应表名即可，目前支持作为 stop / log / watch / pause / resume 的子参数运行 | |
| set | --stream-prepared-cli | 设置写入任务（Job）中活跃写入 slot 的数量 ࠾ --stream-prepared-cli 默认值为 10 ࠾ 示例：mxgate set --stream-prepared-cli 3 |
| --job-interval | 设置写入任务的 ETL（Extract-Transform-Load）工作时间（单位为毫秒，ms） ࠾ --job-interval 默认值为 100 ࠾ 示例：mxgate set --job-interval 150 |
|
| --high-water-mark | 设置目标任务的（写入负载）高水位阈值 ࠾ --high-water-mark 默认值为 0 ࠾ 示例：mxgate set --high-water-mark 20 |
|
| --disable-high-water-mark | 设置是否禁用高水位阈值 ࠾ --disable-high-water-mark 默认值为 false ࠾ 示例：mxgate set --disable-high-water-mark=true |
|
--auto-tune | 设置是否启用自动调节 slot 数的功能 ࠾ 开启所有任务的此功能：mxgate set --auto-tune=true ࠾ 关闭所有任务的此功能：mxgate set --auto-tune=false ࠾ 开启指定任务的此功能：mxgate set --auto-tune=true --job public.t1 |
|
| get | --stream-prepared-get | 获取写入任务（Job）中写入 slot 的数量 ࠾ 示例：mxgate get --stream-prepared-get |
| --stream-status-get | 获取写入任务中写入 slot 的状态 ࠾ 示例：mxgate get --stream-status-get |
|
| --job-interval-get | 获取写入任务的工作时间 ࠾ 示例：mxgate get --job-interval-get |
|
| --job-list | 获取所有的写入任务信息 ࠾ 示例：mxgate get --job-list |
|
| --job-state | 获取所有的写入任务状态 ࠾ 示例：mxgate get --job-state |
|
| --current-config | 获取当前 MatrixGate 进程的配置 ࠾ 示例：mxgate get --current-config |
|
| --kafka-topics | 获取所有的测试主题（Kafka Topic） ࠾ 示例：mxgate get --kafka-topics |
|
| --kafka-messages | 获取某一 Kafka Topic 的所有消息（Messages） ࠾ 示例：mxgate get --kafka-messages |
|
| --source-pressure | 获取目标任务对应的源端数据写入负载 ࠾ 示例：mxgate get --source-pressure |
|
| --high-water-mark-get | 获取为目标任务设定的（写入负载）高水位阈值 ࠾ 示例：mxgate get --high-water-mark-get |
|
--auto-tune-status | 获取写入任务自动调节 slot 数量的状态 ࠾ 获取所有写入任务自动调节 slot 数量的状态：mxgate get --auto-tune-status ࠾ 获取指定任务自动调节 slot 数量的状态：mxgate get --auto-tune-status --job public.t1 |
|
| pause | -X / --disconnect | 暂停 mxgate 时，是否断开 Segment 和 mxgate 之间的 slot（这会导致中断所有 Job 的所有 slot） ࠾ 示例：mxgate pause -X |
| -S / --sync | 不特别运行此子参数的情况下，mxgate 将执行异步暂停；当显式配置此子参数，mxgate 将等待所有数据写入任务（Job）暂停完成再返回结果 ࠾ 示例：mxgate pause -S |
|
| resume | -R / --reload | 恢复写入时，是否重新加载任务的元数据 ࠾ 示例：mxgate resume -R |
| offset-reset | 重设已停止的 Kafka 数据流的消费点位；多条数据流时需先用选择参数定位一条（只有一条时自动选中） ࠾ 示例：mxgate offset-reset --topic csv_test --to-earliest --dry-run ࠾ 详见 Kafka 接入的「重设 Kafka 消费点位」 |
|
| --topic / --consumer-group / --job | 定位要重设的数据流；配置了这几项时须与某一条 flow 完全匹配，没有消费组时省略 `--consumer-group` | |
| --to-earliest | 重置到 Kafka 仍保留的最早点位 | |
| --to-latest | 重置到最新点位（跳过积压） | |
| --to-datetime | 重置到指定时刻及之后的第一条消息 | |
| --to-offsets | 按分区指定点位，例如 `'0:100,1:200'` | |
| --dry-run / --output / -y | 只打印重设计划、不做修改；`--output json` 输出单个 JSON 对象，需配合 `--dry-run` 或 `-y` 使用；`-y` 跳过交互确认，适合自动化场景 | |
| watch | ||
| -D / --daemon-addr | MatrixGate 进程的 gRPC 服务地址（host:port） | -i / --info | 持续打印 mxgate watch 展示出来的相关指标每一列的含义 ࠾ 示例：mxgate watch --info |
| -T / --time | 指定相关监视指标的持续时间（单位为秒，s） ࠾ 默认值为 -1，即不间断打印 ࠾ 示例：mxgate watch --time 200 |
|
| -H / --history | 显示历史指标 ࠾ 示例：mxgate watch --history |
|
| --watch-latency | 持续打印 Latency 相关监控指标 ࠾ 示例：mxgate watch --watch-latency |
|
| --watch-start | 查看历史启动记录，默认当前时间前 24 小时内，如 2022-04-11 11:09:20 ࠾ 示例：mxgate watch --watch-start |
|
| --watch-end | 查看历史终止记录，默认当前时间，如 2022-04-11 11:09:20 ࠾ 示例：mxgate watch --watch-end |
|
| --watch-duration | 查看历史时长 ࠾ 示例：mxgate watch --watch-duration |
注意！
MatrixGate 主要功能介绍请见 MatrixGate 主要功能。
