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 指定源数据的数据格式 textcsvtext 速度最快,但不支持字符类型中出现换行。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 主要功能