MatrixGate 参数
本文档介绍了 MatrixGate 的详细参数信息。
1 配置文件参数
注意！
此部分的参数为 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 | 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 地址 | |
| [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" 时才可配置 |
2 命令行参数
注意！
此部分参数为 mxgate 启动后可在命令行中运行的参数。
注意！
MatrixGate 主要功能介绍请见 MatrixGate 主要功能。