MatrixGate 参数
本文档介绍了 MatrixGate 的详细参数信息。
注意！
实验特性（Experimental）是某特定版本中存在但未正式发布的特性，会在未事先通知的情况下发生语法或实现上的变化或直接删除，请慎用。
1 配置文件
| 参数名 | 默认值 | 参数含义 |
|---|---|---|
| [general]类别 | ||
| -C / --config string | 空 | MatrixGate 要加载的配置文件 |
| -f / --force | 强制终止 MatrixGate 进程 | |
| -p / --pid | -1 | MatrixGate 进程的 ID，目前支持 stop / log / watch / pause / resume 等 |
| -D / --daemon-addr | MatrixGate 进程的 gRPC 服务地址（host:port）， 目前支持 watch 等 |
|
| -n / --lines | 10 | 打印最新的十条日志 |
| -s / --set | 设置某些参数 | |
| -g / --get | 获取某些参数 | |
| --job-interval-get | false | 获取写入任务的工作时间 |
| --job-list | false | 获取所有的写入任务信息 |
| --job-state | false | 获取所有的写入任务状态 |
| --stream-prepared-get | 11 | 获取写入任务中写入连接的数量 |
| --stream-status-get | false | 获取写入任务中写入连接的状态 |
| --stream-prepared-cli | 0 | 写入任务中活跃写入连接的数量 |
| --status | 获取当前 MatrixGate 进程的状态 | |
| --current-config | 获取当前 MatrixGate 进程的配置 | |
| --kafka-topics | 获取所有的测试主题（Kafka Topic） | |
| --kafka-messages | 获取某一 Kafka Topic 的所有消息（Messages） | |
| --job-interval | 任务的 ETL（Extract-Transform-Load）工作时间 | |
| --pause | false | 中断写入 |
| --resume | false | 恢复写入 |
| -X / --disconnect | 当 mxgate 暂停时，是否断开 Segment 和 mxgate 之间的连接 | |
| -R / --reload | 是否重新加载任务的元数据 | |
| -S / --sync | false | 默认情况下，我们将执行异步暂停，当 sync == true，将等待所有数据插入任务暂停完成 |
| --job | 需要设置参数的任务 | |
| -w / --watch | 持续打印 watch 相关的监控指标 | |
| -i / --info | 打印 mxgate watch 展示出来的相关指标每一列的含义 | |
| -T / --time | -1，即不间断打印 | 指定相关监视指标的持续时间（秒） |
| --watch-latency | false | 打印 Latency 相关监控指标 |
| --watch-start | now-24h | 查看历史启动记录，默认当前时间前 24 小时内，如 2022-04-11 11:09:20 |
| --watch-end | now | 查看历史终止记录，默认当前时间，如 2022-04-11 11:09:20 |
| --watch-duration | 1h | 查看历史时长 |
| -H / --history | 显示历史指标 | |
| [database]类别 | ||
| --db-database | postgres | MatrixGate 连接 MatrixDB 数据库名 |
| --db-master-host | 本机主机名 | MatrixGate 连接 MatrixDB 主机名 |
| --db-master-port | 5432 | MatrixGate 连接 MatrixDB 主机端口号 |
| --db-user | 当前系统用户名 | MatrixGate 连接 MatrixDB 用户名 注意！ 该用户必须具有创建外部表的权限，如果使用的是非超级权限用户，请使用如下命令增加权限： alter user {username} CREATEEXTTABLE; |
| --db-password | 空 | MatrixGate 连接 MatrixDB 用户密码 |
| --db-max-conn | 10 | MatrixGate 连接 MatrixDB 最大连接数 |
| [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）的映射模板的文件路径。 v4.8.2 版本中作为[实验特性]开始支持 TEXT / CSV 格式 |
|
| [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 表示禁用 |
|
| -h / --help | 打印 MatrixGate 用法 | |
| --version | 打印 MatrixGate 版本 | |
| --no-cleanup | 即使在正常退出时也保留临时模式 | |
| --grpc-port | 访问 gRPC 信息的端口，0 表示禁用 |
|
| [metrics]类别 | ||
| --metrics-enable | true | 启用指标 |
| --metrics-sample-interval | 3 | 指标的采样间隔（秒）。将其设置为 >0 以启用指标收集（会降低性能） |
| [source]类别 | ||
| --source | http | MatrixGate 数据来源，支持 http / stdin / kafka / transfer / grpc。v4.8.2 版本中作为[实验特性]开始提供所有数据源类型下的 JSON 格式数据的解析及映射支持 |
| [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 地址 | |
| [transform]类别 | ||
| --transform | plain | 将写入的数据进行格式或类型转换。支持 plain / json / nil / tsbs / hanagdbc |
| [writer]类别 | ||
| --interval | 100 毫秒 | MatrixGate 执行批量数据加载时间周期 |
| --writer | stream | mxgate 通过 Writer 将数据写入到 MatrixDB。支持 stream / nil |
| --stream-prepared | 10 | 插入工作进程并行度 |
| --stream-host | mdw | MatrixDB 中 Master 连接到 MatrixGate 的主机名。这是为了系统有多个网络接口 |
| --use-gzip | auto | MatrixGate 向 Segment 发送数据时是否开启压缩，可配置参数为 auto/yes/no。auto 设置下优先选用 zstd 压缩算法，如果目标数据库不支持（4.8.0 版本之前），则自动退化为 gzip 压缩算法，如果 gzip 也不支持则不压缩；如果强制设为 --use-gzip=no，则会禁止压缩传输。此设置虽能节省少量 CPU 占用，但是会大大增加网络传输数据量，我们建议除非为单机部署的数据库，且 mxgate 和数据库全部在同一台主机上，否则慎用 no 设置，一律采用默认值 auto 即可 |
| --max-seg-conn | 128 | 外部表从 MatrixGate 拉取数据时启动的 Segment 数量，调大该参数会增加网络连接资源 |
| --timing | false | 开启该参数后，MatrixGate 在记录日志时会为每条 INSERT 增加耗时信息 |
| --insert-timeout | 600000 | MatrixGate 执行 INSERT 语句超时时间。设置大于 0 的值后会在等待毫秒单位配置时间后超时 |
| -I / --instrumentation [实验特性， v4.8.2 支持] | disable | 开启单个槽（Slot）或者多个槽的数据插入全流程观测。支持 disable / single / all：disable：关闭插入流程的观测single：开启 0 号槽的观测all：开启所有槽的观测 |
2 命令行参数
| 命令行参数名 | 参数含义 |
|---|---|
| --run | 在命令行运行 MatrixGate |
| --start | 启动 MatrixGate 后台进程 |
| --stop | 终止 MatrixGate 后台进程 |
| --status | 打印 MatrixGate 后台进程的状态 |
| --config | 打印配置文件完整模版 |
| --log | 显示日志 |
| --set | 设置某些参数 |
| --get | 获取某些参数 |
| --watch | 观测 MatrixGate 守护进程指标，你可以执行 mxgate watch --info 获取观测表的列名 |
| --version | 显示版本 |
| --help | 显示用法和参数列表 |
注意！
MatrixGate 主要功能介绍请见 MatrixGate 主要功能。