MatrixOne supports logical backups through the mo_dump utility. mo_dump is a command-line utility designed to generate logical backups of the MatrixOne database. It produces SQL statements that can be used to recreate database objects and data.
./mo-dump -u ${user} -p ${password} -h ${host} -P ${port} -db ${database} [--local-infile=true] [--enable-escape=false] [-csv] [-no-data] [-tbl ${table}...] [-confirm-permanent-table ${table}]... -net-buffer-length ${net-buffer-length} > {dumpfilename.sql}
参数释义
-
-u [user]：连接 MatrixOne 服务器的用户名。只有具有数据库和表读取权限的用户才能使用
mo-dump实用程序，默认值 dump。 -
权限要求：除目标数据库/表的读取权限外，账号还需要系统表
mo_catalog.mo_database、mo_catalog.mo_tables与mo_catalog.mo_indexes的 SELECT 权限（mo_indexes用于识别索引隐藏表，避免其被误导出或误删用户表）。受限账号可执行：GRANT SELECT ON TABLE mo_catalog.mo_database TO <role>; GRANT SELECT ON TABLE mo_catalog.mo_tables TO <role>; GRANT SELECT ON TABLE mo_catalog.mo_indexes TO <role>;
-
-p [password]：MatrixOne 用户的有效密码。默认值：111。
-
-h [host]：MatrixOne 服务器的主机 IP 地址。默认值：127.0.0.1
-
-P [port]：MatrixOne 服务器的端口。默认值：6001
-
-db [数据库名称]：必需参数。要备份的数据库的名称。可以指定多个数据库，数据库名称之间用
,分隔。-db all表示导出当前账户可见的全部用户数据库；内置系统库（information_schema、mo_catalog、mo_debug、mo_task、mysql、system、system_metrics）会被跳过。如果当前账户没有用户数据库，导出会以明确错误退出，不会生成空备份。 -
-net-buffer-length [数据包大小]：数据包大小，即 SQL 语句字符的总大小。数据包是 SQL 导出数据的基本单位，如果不设置参数，则默认 1048576 Byte（1M），最大可设置 16777216 Byte（16M）。假如这里的参数设置为 16777216 Byte（16M），那么，当要导出大于 16M 的数据时，会把数据拆分成多个 16M 的数据包，除最后一个数据包之外，其它数据包大小都为 16M。
-
-csv：默认值为 false。当设置为 true 时表示导出的数据为 CSV 格式。
-
-csv-field-delimiter：默认值为逗号，指定一个 UTF-8 字符作为 CSV 字段分隔符。不能使用反斜杠、双引号、回车、换行或 NUL；反斜杠与
LOAD DATA的转义及 NULL 标记冲突，会在连接数据库前拒绝导出。 -
--local-infile：默认值为 true，仅在参数 -csv 设置为 true 时生效。为 true 时，恢复脚本按 CSV 文件名从导入客户端的当前目录读取；搬迁备份时将 SQL 和 CSV 一起拷贝，并从 CSV 所在目录执行导入。为 false 时，脚本保留导出 CSV 的绝对路径，恢复服务器必须能访问该路径。
-
-tbl [表名]：可选参数。如果参数为空，则导出整个数据库。如果要备份指定表，则可以在命令中指定多个
-tbl和表名。 -
-confirm-permanent-table [表名]：可重复的用户确认选项，允许单库整库导出包含名字具有历史临时表形态的永久表，详见下文。仅允许一个明确的
-db；不支持-db all、多库、订阅库或与-tbl选表组合。 -
-no-data：默认值为 false。当设置为 true 时表示不导出数据，仅导出表结构。
-
-enable-escape：默认值为 false，仅在参数 -csv 设置为 true 时生效。表示对特殊字符开启转义，可以避免一些兼容性问题。
Tips: 需要安装 Go（支持自动工具链选择的 Go 1.21 或更新版本）、C/C++ 编译器、make、tar 和 shasum。构建会选用 go.mod 指定的 Go 1.26.4，从固定版本 MatrixOne 模块的已校验源码归档构建静态 jemalloc，不需要安装整个 MatrixOne 内核或在运行时携带 jemalloc 动态库。
视图依赖使用 MatrixOne 9dfe5c1be92e 的完整 SQL parser；支持语法随该依赖版本演进，不再使用字符串匹配或手写 SQL 子集，对真实循环返回错误而不是无限重排。分析和恢复使用每个视图在 mo_catalog.mo_tables.viewdef 中持久化的源语句、默认库及解析模式，不使用导出连接的 SQL mode 猜测视图语法。保留源语句内容；持久化语句为 ALTER VIEW 时，仅将首个语句动词改为 CREATE，用于在空目标上重建视图。历史记录缺少模式字段时遵循服务端 legacy 规则。元数据缺失或损坏会明确报错；若 DefaultDatabase 缺失、为 null 或空字符串，且视图需要解析未限定数据库的物理关系，也会明确拒绝导出，不猜测其所属库就是创建默认库。无需默认库的常量、CTE-only 和全限定引用仍可导出。
恢复脚本先保存原 @@SESSION.sql_mode，在恢复期间临时移除 NO_BACKSLASH_ESCAPES，保证数据字符串和 CSV 路径的转义有效，成功结束后恢复原 mode。每个视图使用独立于脚本级变量的临时变量保存当前 mode，通过 SET SESSION sql_mode 应用其持久化解析标志，并保留目标会话的非解析策略；成功执行该视图段落后恢复进入该段落时的 mode。不修改全局 SQL mode 或目标的 lower_case_table_names，目标仍需兼容的名称解析规则。导入客户端必须正确切分语句并支持这些会话设置，尤其是 NO_BACKSLASH_ESCAPES 字面量；不能仅凭导入退出码判断恢复完整。恢复不是原子操作，出错时可能留下部分对象或尚未恢复的会话设置。
导出时先输出所有选中数据库的普通表及数据，再对选中的跨库视图统一依赖排序。未选中的外部对象和历史快照仍需在恢复环境中可用。
-
执行下面的代码即可从 MatrixOrigin/mo_dump 源代码构建
mo-dump二进制文件：git clone https://github.com/matrixorigin/mo_dump.git cd mo_dump make build -
你可以在 mo_dump 文件夹中找到
mo-dump可执行文件：mo-dump。 -
make test会使用相同 Go 工具链及当前工作区 native 依赖运行测试。直接执行 Go 命令时先运行make jemalloc，并设置：export GOTOOLCHAIN=go1.26.4 GOWORK=off export CGO_CFLAGS="-I$PWD/thirdparties/install/include" export CGO_LDFLAGS="-L$PWD/thirdparties/install/lib" go test -mod=readonly ./...
!!! note
构建好的 mo-dump 文件也可以在相同的硬件平台上工作。但是需要注意在 x86 平台中构建的 mo-dump 二进制文件在 Darwin ARM 平台中则无法正常工作。你可以在同一套操作系统和硬件平台内构建并使用 mo-dump 二进制文件。mo-dump 目前只支持 Linux 和 macOS。
mo-dump 在命令行中非常易用。参见以下步骤示例，导出 sql 文件格式完整数据库：
在你本地计算机上打开终端窗口，输入以下命令，连接到 MatrixOne，并且导出数据库：
./mo-dump -u username -p password -h host_ip_address -P port -db database > exporteddb.sql
例如，如果你在与 MatrixOne 实例相同的服务器中启动终端，并且你想要生成单个数据库的备份，请运行以下命令。该命令将在 t.sql 文件中生成 t 数据库的结构和数据的备份。t.sql 文件将与您的 mo-dump 可执行文件位于同一目录中。
./mo-dump -u root -p 111 -h 127.0.0.1 -P 6001 -db t > t.sql
如果你想将数据库 t 内的表导出为 CSV 格式，参考使用下面的命令：
./mo-dump -u root -p 111 -db t -csv --local-infile=false > ttt.csv
如果要在数据库中生成单个表的备份，可以运行以下命令。该命令将生成命名为 t 的数据库的 t1 表的备份，其中包含 t.sql 文件中的结构和数据。
./mo-dump -u root -p 111 -db t -tbl t1 > t1.sql
mo-dump支持导出多个数据库。[在 -db后接数据库名] 例如
mo-dump -u dump -p xxx -h 127.0.0.1 -P 6001 -db db1,db2,db3 > /tm/db1-db2-db3.sql
mo-dump -u dump -p xxx -h 127.0.0.1 -P 6001 -db all > /tm/all-dbs.sqlmo-dump不仅支持导出多个数据库，还支持导出多个数据库表。 例如
mo-dump -u dump -p xxx -h 127.0.0.1 -P 6001 -db db1 -tbl tbl1,tbl2,tbl3 > /tm/all-dbs.sql普通/空 relkind 的表如果具有 __mo_tmp_<32 位小写十六进制>_... 名字，现有元数据无法可靠区分其是永久表还是历史会话临时表。因此默认整库导出会拒绝猜测。确认它们确为永久表后，可以逐个声明，并继续导出整个数据库：
./mo-dump -u root -p 111 -db example \
-confirm-permanent-table '__mo_tmp_0123456789abcdef0123456789abcdef_orders' \
-confirm-permanent-table '__mo_tmp_0123456789abcdef0123456789abcdef_items' > example.sql- 这是用户对表身份的确认，不是服务端的证明。错误确认可能导出历史临时表残留数据；不确定时不要使用。 不需要升级或修改 MatrixOne。
- 名单不是导出白名单：未列入名单的普通表、视图等仍按原规则随整库导出。每个有歧义的候选表都必须确认；缺少任何一项仍拒绝整个导出。
- 每次选项接收一个目录中的原始表名，精确匹配（包括大小写）；不按逗号拆分、不解析 SQL 引号、不支持通配符。特殊字符用 shell 引号保护，不要额外添加 SQL 反引号。重复名字按同一个确认处理，空字符串报错。
- 不存在、拼错、无须确认或被过滤的名字都会报错，不会静默忽略。确认不能越过当前租户/库范围、权限检查、明确的临时 relkind、索引登记或内部对象过滤；订阅库无法通过当前库目录验证该名单，也会明确拒绝。
- SQL、
-csv、-no-data使用相同的确认规则。确认/读取失败时，进程非零退出，不向 stdout 发布脚本，不发布本次 CSV，也不会改动已有 CSV 文件。与其他导出一样，shell 的>重定向可能在程序启动前就截断已有 SQL 文件，应使用新的输出文件名。
- 用户
SEQUENCE会随整库/多库导出一并导出：mo-dump 按序列的当前定义（含ALTER SEQUENCE后的参数）重建CREATE SEQUENCE，并回放其分配状态（last_seq_num/is_called），恢复后的序列从断点继续分配，不会重复使用已消费的值。脚本中序列先于依赖它的表导出。 -no-data只导出定义：此时不回放序列进度，恢复后的序列从定义的START WITH开始分配；若序列的进度状态本身已不可回放（见下一条），只要定义仍合法，-no-data仍可成功导出。- 序列状态回放使用三参数形式的
SELECT setval('序列名', n, 第三参数)，依赖当前 MatrixOne 主线版本的SETVAL语义（SETVAL(n, true)后下一个NEXTVAL返回 n、SETVAL(n, false)后返回 n+increment）；较旧版本服务器恢复该语句时行为可能不同。 - 如果序列的分配状态无法被精确重建（例如
ALTER SEQUENCE后last_seq_num越出当前的[MINVALUE, MAXVALUE]，此时SETVAL在恢复时会拒绝），携带进度的导出会以明确错误失败，而不是生成一个到恢复阶段才失败的“成功”备份；此时可改用-no-data导出仍然合法的定义。 - 输出安全：完整 SQL 脚本先暂存在当前目录的隐藏临时文件中，在全部导出成功之前不会有任何字节到达 stdout；导出路径上的任何失败都以非零退出码结束且不产生脚本输出，不会留下只包含
DROP DATABASE的危险半成品。仅在最后的发布阶段，如果输出通道本身故障（例如消费端提前关闭管道），已写入的字节无法取回——SIGPIPE 被忽略并转为写错误上报，错误信息会报告已发出的精确字节数，且退出码非零，请勿将该前缀片断当作备份使用。/* MODUMP SUCCESS ... */标记始终是全输出的最后一条（在 CSV 提示之后）：看到它意味着脚本、CSV 数据文件及其路径提示都已成功交付；标记之前任何一步失败都会输出非零退出码，而非零退出码的运行不会发布任何 csv 数据文件。CSV 数据文件同样先以隐藏临时文件暂存；发布名在写入数据前就以独占方式（O_EXCL）预留在最终路径上，随机后缀与其他导出冲突时会换名重试，因此一次导出永远不会覆盖、截断或事后删除其他导出的文件；导出失败时本次运行预留和已发布的所有文件都会被清理。发布后的 CSV 文件权限遵循当前进程的 umask 策略（0666 去掉 umask 位，例如 umask 022 时为 0644），与os.Create一致，便于由其他系统用户恢复。（进程不可中断信号终止的场景可能遗留隐藏暂存文件，可安全删除。）
mo-dump导出不锁定源库，也不是一致性快照：导出期间持续写入的库，表与表之间、表与序列状态之间的一致性无法保证。需要一致备份时请在写入静默窗口导出，或配合其他一致性措施。mo-dump暂不支持只导出数据库的结构或数据。如果你想在没有数据库结构的情况下生成数据的备份，或者仅想导出数据库结构，那么，你需要手动拆分.sql文件。