Prisma 服务数据导入导出实战:NDF 格式、prisma import/export 命令与原始 HTTP API 全解析
Prisma 服务数据导入导出实战:NDF 格式、prisma import/export 命令与原始 HTTP API 全解析
本篇技术指南以 Prisma(prisma1)文档体系中的 Data Import & Export 章节 为骨架,系统讲解 Prisma 服务的数据导入(Import)与导出(Export)机制:先剖析导入导出共用的统一中间格式 Normalized Data Format(NDF),再分别给出 prisma import / prisma export 命令行用法与裸 /import、/export HTTP API 的调用方式,并结合本仓库 prisma-cli-core 的源码实现(Importer.ts、Exporter.ts、Validator.ts)揭示底层原理。读完本文,你将能够独立完成一个 Prisma 服务的数据备份、迁移与跨 stage(如 dev 到 prod)数据复制,并理解其幂等性与校验边界。
一、NDF:导入导出共用的统一中间格式
Normalized Data Format(NDF)是 Prisma 服务数据导入导出所使用的中间数据格式,它规定了 JSON 的一种特定结构。无论是通过 CLI 还是原始 HTTP API,所有进出 Prisma 服务的数据都必须符合 NDF。
NDF 将数据按"值类型(value type)"拆分为三类,分别描述节点数据的三个不同侧面:
| 值类型 | 内容 |
|---|---|
nodes |
节点的标量字段(scalar fields)数据,即数据库记录本身 |
lists |
节点的标量列表字段(scalar list fields)数据 |
relations |
通过关系字段(relation fields)连接两个节点的关系数据 |
任何一份 NDF JSON 文档在顶层都是一个包含两个键的对象:
valueType:标注这份数据属于哪种值类型,取值只能是"nodes"、"lists"或"relations";values:真正承载数据的数组,其内部元素结构随valueType不同而变化。
为便于说明,后续示例统一基于以下数据模型:
type User {
id: String! @unique
firstName: String!
lastName: String!
hobbies: [String!]!
partner: User
}
1.1 Nodes:标量字段数据
当 valueType 为 "nodes" 时,values 数组内每个对象的结构为:
{
"valueType": "nodes",
"values": [
{ "_typeName": STRING, "id": STRING, "<scalarField1>": ANY, "<scalarField2>": ANY, ..., "<scalarFieldN>": ANY },
...
]
}
其中 _typeName 和 id 均为字符串:_typeName 指数据模型中的 SDL 类型名(如 User),id 是该节点的唯一标识;<scalarFieldX> 占位符对应 SDL 类型中各个标量字段的名称。
例如,导入两个 User 节点的标量值:
{
"valueType": "nodes",
"values": [
{"_typeName": "User", "id": "johndoe", "firstName": "John", "lastName": "Doe"},
{"_typeName": "User", "id": "sarahdoe", "firstName": "Sarah", "lastName": "Doe"}
]
}
1.2 Lists:标量列表字段数据
当 valueType 为 "lists" 时,values 数组内每个对象的结构为:
{
"valueType": "lists",
"values": [
{ "_typeName": STRING, "id": STRING, "<scalarListField>": [ANY] },
...
]
}
与 nodes 不同,lists 类型的每个对象只能为一个标量列表字段提供值(例如一个对象不能同时携带 hobbies 和 favorites 两个列表字段)。
例如,导入两个 User 节点的 hobbies 列表字段:
{
"valueType": "lists",
"values": [
{"_typeName": "User", "id": "johndoe", "hobbies": ["Fishing", "Cooking"]},
{"_typeName": "User", "id": "sarahdoe", "hobbies": ["Biking", "Coding"]}
]
}
1.3 Relations:关系数据
当 valueType 为 "relations" 时,values 数组内每个元素本身就是一对对象(一个始终恰好包含两个元素的数组),而不是单个对象:
{
"valueType": "relations",
"values": [
[
{ "_typeName": STRING, "id": STRING, "fieldName": STRING },
{ "_typeName": STRING, "id": STRING, "fieldName": STRING }
],
...
]
}
其中 _typeName、id、fieldName 均为字符串,fieldName 是某个 SDL 类型上关系字段的名称。这一对对象描述"通过哪个关系字段、把哪两个节点连接起来"。
例如,通过 partner 关系字段把 johndoe 与 sarahdoe 两个 User 节点关联起来:
{
"valueType": "relations",
"values": [
[
{ "_typeName": "User", "id": "johndoe", "fieldName": "partner" },
{ "_typeName": "User", "id": "sarahdoe", "fieldName": "partner" }
]
]
}
1.4 源码佐证:校验器如何理解这三种结构
仓库中 Validator.ts 的 validateImportData 正是按照上述三种 valueType 分派校验逻辑的:nodes 走 validateNode,lists 走 validateListNode,relations 走 validateRelationTuple。其中关系元组被强制要求"必须是数组"且"恰好包含 2 个节点"(见 Validator.ts),并校验 fieldName 必须指向数据模型中真实存在的关系字段。同时,仓库在 import/fixtures/basic 目录下提供了可直接阅读的 NDF 样例(如 lists/000001.json 展示了 Post 模型 tags 列表字段的导入数据),其配套数据模型定义在 types.graphql,可作为编写 NDF 文件的参考模板。
二、数据导入:从数据源到 Prisma 服务的两阶段流程
2.1 整体流程与现状
导入过程可以抽象为两个阶段:
+--------------+ +----------------+ +------------+
| SQL / MongoDB | (1) transform | NDF | (2) chunked upload | Prisma |
| JSON 等数据源 | +--------------> | | +-------------------> | |
+--------------+ +----------------+ +------------+
- 阶段一(数据转换):把 MySQL、MongoDB、Firebase 等具体数据源转换为 NDF。截至文档版本,这一步骤必须手动完成——CLI 尚未内置这些数据源的直接导入能力(仓库源码也印证了这一点:import/index.ts 中当
databaseType === 'document'(即 MongoDB)时直接抛错,提示改用数据库原生导入工具)。 - 阶段二(分块上传):将 NDF 数据上传到 Prisma 服务。可以通过
prisma import命令,也可以直接调用原始 import API。
在阶段二上传 NDF 文件时,数据需要按三种"种类"拆分到 nodes、lists、relations 三类文件中。每种类型的文件数量不限,但建议每个文件不超过 1 MB,否则可能触发超时(timeout)。
2.2 幂等性与数据校验:两条必须牢记的警告
幂等性(Idempotency):导入操作不是幂等的。每次运行导入总是向服务新增数据,从不更新已存在的节点。因此,同一份数据集导入多次会导致未定义行为;例如,用相同的 id 导入同一个节点多次,很可能破坏你的服务。
数据校验(Data Validation):原始 import API 对待导入数据不做任何校验;只有通过 CLI 导入时才会执行基础校验(详见下文 2.5)。导入无效数据会导致未定义行为甚至破坏服务,保证数据有效性是服务维护者的责任。一个稳妥的做法是:先对数据模型完全相同的服务做一次导出,用导出的 NDF 数据作为参照来检查将要导入的数据。
2.3 使用 CLI 导入:prisma import --data
Prisma CLI 提供 prisma import 命令(源码入口见 import/index.ts)。核心选项:
| 选项 | 短选项 | 说明 |
|---|---|---|
--data |
-d |
指向包含待导入数据的目录(可以是普通目录或 zip 压缩目录),必填 |
除此之外,命令还支持 --env-file(-e,注入环境变量的 .env 文件路径)与 --project(-p,Prisma 定义文件路径)两个辅助选项(见 import/index.ts)。
与裸 API 相比,使用 CLI 导入有以下优势:
- 可一次上传多个文件,无需逐个上传;
- 复用 CLI 自身的认证机制,不必手工携带认证 token;
- 支持暂停与恢复正在进行的导入(断点续传,见 2.4);
- 未来计划支持直接从 MySQL、MongoDB、Firebase 等数据源导入(当前版本尚未提供)。
2.4 输入格式:目录结构与文件编号规则
使用 CLI 导入时,NDF 数据文件必须放在以其类型命名的目录下:nodes、lists、relations。每个文件都必须是遵循 NDF 结构的 JSON 文件,因此必须以 .json 结尾;且放置在各自目录中的 .json 文件需要从 1 开始递增编号,文件名可以任意补零,如 1.json、01.json、0000001.json 都是合法的。
一个完整的 Prisma 服务导入项目结构如下:
.
├── data
│ ├── lists
│ │ ├── 0001.json
│ │ ├── 0002.json
│ │ └── 0003.json
│ ├── nodes
│ │ ├── 0001.json
│ │ └── 0002.json
│ └── relations
│ └── 0001.json
├── datamodel.graphql
└── prisma.yml
其中 data 目录内是符合 NDF 的数据文件,然后在终端执行:
prisma import --data data
源码层面,Importer.ts 的实现细节与目录约定完全对应:
- zip 支持:若
--data指向的是 zip 文件,unzip()会先用adm-zip将其解压到当前工作目录下的.import/临时目录(Importer.ts); - 文件收集:
getFiles()用globby分别扫描lists/、nodes/、relations/三个子目录下的*.json文件(Importer.ts); - 编号解析:
getNumber()通过正则/.*?(\d+)\.json/从文件名中解析出序号(Importer.ts),用于断点续传判断; - 上传顺序:严格按
nodes→lists→relations的顺序分块上传,每块结束都会把进度写入.import/state.json(Importer.ts)。
断点续传原理:state.json 记录 nodes、lists、relations 各自已上传到的文件序号。重新执行导入时,getState() 读取该文件(缺失时回退到全 0 的 defaultState),上传循环中若 state.nodes >= n 则跳过该文件并打印 Skipping file ... (already imported)(Importer.ts)。这就是"暂停与恢复"能力的具体实现。导入成功后 saveState(defaultState) 重置状态并清理临时目录。
2.5 CLI 导入附带的基础数据校验
CLI 导入与裸 API 的一大区别在于会执行基础校验(validateFiles,见 Importer.ts):如果 nodes、lists、relations 三个目录均为空,直接抛出异常;否则对每份文件调用 Validator.validateImportData。
Validator.ts 定义的校验规则相当细致,可总结为:
- 结构必填:
values属性必须存在且为数组(Validator.ts); - 节点必填项:每个对象必须有
_typeName(且该类型必须存在于数据模型中)和字符串类型的id(Validator.ts); - 必填字段完整性:数据模型中标为必填(NonNull)的标量/列表字段在导入数据中不得缺失(
checkRequiredFields); - 未知字段检查:对象中不允许出现数据模型之外的字段,
createdAt、updatedAt、id为内置白名单(Validator.ts); - 类型校验:按字段的深层类型调用对应校验器——
ID/String用isString,Int校验整型语义,Float用isNumber,Boolean用isBoolean,Json要求是对象,DateTime则用正则\d{4}-<a href="https://link.gitcode.com/i/78ba4667755bbe05a9ed2238b5846be5" target="_blank">01]\d-[0-3]\dT[0-2]\d:[0-5]\d:[0-5]\d\.\d+([+-][0-2]\d:[0-5]\d|Z)匹配带毫秒与时区/Z后缀的日期字符串([Validator.ts); - 枚举校验:数据模型中定义的枚举类型会被自动转成枚举值白名单校验器(
makeEnumValidators); - 列表语义:
nodes数据中不允许出现列表字段值,lists数据中不允许出现单值标量字段,列表值本身必须是数组(Validator.ts)。
2.6 使用原始 import API
原始 import API 暴露在服务 HTTP 端点的 /import 路径下,例如:
http://localhost:60000/my-app/dev/importhttps://database.prisma.sh/my-app/prod/import
单次请求最多可上传 10 MB 的 NDF JSON 数据,且必须在 HTTP 请求头 Authorization 中携带认证 token。
下面是一个用 curl 上传 nodes 类型 NDF 数据的完整示例:
curl 'http://localhost:60000/my-app/dev/import' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJPbmxpbmUgSldUIEJ1aWxkZXIiLCJpYXQiOjE1MTM1OTQzMTEsImV4cCI6MTU0NTEzMDMxMSwiYXVkIjasd3d3LmV4YW1wbGUuY29tIiwic3ViIjoianJvY2tldEBleGFtcGxlLmNvbSIsIkdpdmVuTmFtZSI6IkpvaG5ueSIsIlN1cm5hbWUiOiJSb2NrZXQiLCJFbWFpbCI6Impyb2NrZXRAZXhhbXBsZS5jb20iLCJSb2xlIjpbIk1hbmFnZXIiLCJQcm9qZWN0IEFkbWluaXN0cmF0b3IiXX0.L7DwH7vIfTSmuwfxBI82D64DlgoLBLXOwR5iMjZ_7nI' \
-d '{"valueType":"nodes","values":[{"_typeName":"Model0","id":"0","a":"test","b":0,"createdAt":"2017-11-29 14:35:13"},{"_typeName":"Model1","id":"1","a":"test","b":1},{"_typeName":"Model2","id":"2","a":"test","b":2,"createdAt":"2017-11-29 14:35:13"},{"_typeName":"Model0","id":"3","a":"test","b":3},{"_typeName":"Model3","id":"4","a":"test","b":4,"createdAt":"2017-11-29 14:35:13","updatedAt":"2017-11-29 14:35:13"},{"_typeName":"Model3","id":"5","a":"test","b":5},{"_typeName":"Model3","id":"6","a":"test","b":6},{"_typeName":"Model4","id":"7"},{"_typeName":"Model4","id":"8","string":"test","int":4,"boolean":true,"dateTime":"1015-11-29 14:35:13","float":13.333,"createdAt":"2017-11-29 14:35:13","updatedAt":"2017-11-29 14:35:13"},{"_typeName":"Model5","id":"9","string":"test","int":4,"boolean":true,"dateTime":"1015-11-29 14:35:13","float":13.333,"createdAt":"2017-11-29 14:35:13","updatedAt":"2017-11-29 14:35:13"}]}' \
-sSv
使用占位符的通用形式为:
curl '__SERVICE_ENDPOINT__/import' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer __JWT_AUTH_TOKEN__' \
-d '{"valueType":"__NDF_TYPE__","values": __DATA__ }' \
-sSv
三、数据导出:CLI 与原始 export API
导出数据同样有 CLI 与原始 API 两条路径,两种方式下载到的数据都是 JSON 格式且遵循 NDF。由于导出结果本身就是 NDF,可以直接导入到 schema 完全相同的另一个服务——例如为 dev stage 准备测试数据,这正是"备份—恢复"与"环境复制"工作流的核心。
3.1 使用 CLI 导出:prisma export
Prisma CLI 提供 prisma export 命令。原 1.14 文档中记录其核心选项为 --export-path(短选项 -e),指向一个由 CLI 创建、用于存放导出数据的 zip 文件路径;在当前仓库的 prisma-cli-core 源码 export/index.ts 中,该标志已实现为 --path(短选项 -p),且未传入时默认生成 export-<ISO时间戳>.zip,路径若不是以 .zip 结尾会被自动补全。命令同样支持 --env-file(-e)与 --project 辅助选项。
与裸 API 相比,使用 CLI 导出有以下优势:
- 复用 CLI 认证机制,无需手工携带认证 token;
- 直接将下载数据写入文件系统,并自动打包为 zip;
- 内置游标(cursor)管理:当数据量需要多次请求才能全部导出时,CLI 会自动携带并更新游标,手动调用 API 则需自行发送多次请求并每次调整游标。
3.2 输出格式
导出的数据按 NDF 组织,放在三个以 NDF 类型命名的目录下:nodes、lists、relations。
3.3 源码实现:Exporter 的下载循环
Exporter.ts 完整实现了上述 CLI 能力,其 download() 流程为(Exporter.ts):
makeDirs()在本地.export/临时目录下创建nodes/、lists/、relations/三个子目录;- 依次调用
downloadFiles('nodes', ...)、downloadFiles('lists', ...)、downloadFiles('relations', ...); zipIt()用archiver把三个目录打包成 zip 写入目标路径;- 清理临时目录
.export/。
downloadFiles 的游标循环逻辑(Exporter.ts)很有参考价值:游标初始化为 {table: 0, row: 0, field: 0, array: 0},循环条件 cursorSum(cursor) >= 0 即"四个分量求和仍大于等于 0 就继续请求";每次响应中拿到新的 cursor 后进入下一轮,直到返回的游标四个分量均为 -1(终止态)为止。每个响应被写为独立文件,文件名用 leadingZero 做 6 位零填充(000001.json、000002.json……),内容结构为 {"valueType": fileType, "values": data.out.jsonElements}。仓库 export/download/nodes/000001.json 即一份真实的导出样例,展示了导出的 nodes 数据中每个节点包含 _typeName、id、createdAt、updatedAt 及各标量字段的完整形态。
3.4 使用原始 export API
原始 export API 暴露在服务 HTTP 端点的 /export 路径下,例如:
http://localhost:60000/my-app/dev/exporthttps://database.prisma.sh/my-app/prod/export
单次请求最多可下载 10 MB 的 NDF JSON 数据,同样需要在 Authorization 请求头携带认证 token。端点接收 POST 请求,请求体为如下 JSON:
{
"fileType": "nodes",
"cursor": {
"table": 0,
"row": 0,
"field": 0,
"array": 0
}
}
cursor 中的四个值描述从数据库的哪个偏移位置开始导出数据。每次导出响应都会返回一个新的游标,它处于两种状态之一:
- 终止态(数据已全部导出):
table、row、field、array四个值全部返回-1,表示导出已完成; - 非终止态(本响应已满 10 MB):只要四个值中有任何一个不等于
-1,就说明本次响应已达 10 MB 上限,此时应把返回的cursor值作为下一次导出请求的输入继续拉取,直到游标进入终止态。
一个完整的 curl 调用示例(请求 nodes 类型数据):
curl 'http://localhost:60000/my-app/dev/export' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJPbmxpbmUgSldUIEJ1aWxkZXIiLCJpYXQiOjE1MTM1OTQzMTEsImV4cCI6MTU0NTEzMDMxMSwiYXVkIjasd3d3LmV4YW1wbGUuY29tIiwic3ViIjoianJvY2tldEBleGFtcGxlLmNvbSIsIkdpdmVuTmFtZSI6IkpvaG5ueSIsIlN1cm5hbWUiOiJSb2NrZXQiLCJFbWFpbCI6Impyb2NrZXRAZXhhbXBsZS5jb20iLCJSb2xlIjpbIk1hbmFnZXIiLCJQcm9qZWN0IEFkbWluaXN0cmF0b3IiXX0.L7DwH7vIfTSmuwfxBI82D64DlgoLBLXOwR5iMjZ_7nI' \
-d '{"fileType":"nodes","cursor":{"table":0,"row":0,"field":0,"array":0}}' \
-sSv
使用占位符的通用形式为:
curl '__SERVICE_ENDPOINT__/export' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer __JWT_AUTH_TOKEN__' \
-d '{"fileType":"__NDF_TYPE__","cursor": {"table":__TABLE__,"row":__ROW__,"field":__FIELD__,"array":__ARRAY__}} }' \
-sSv
四、限制与实操建议
4.1 文档型数据库(MongoDB)暂不支持
仓库源码 import/index.ts 与 export/index.ts 均明确:当服务的 databaseType 为 document(即 MongoDB)时,prisma import / prisma export 会直接抛错,建议改用数据库的原生导入导出工具(如 mongorestore / mongodump)。因此,本文所述的数据导入导出能力适用于关系型数据库(Postgres、MySQL)场景。
4.2 命令演进与弃用提示
从源码可以看到,prisma1 的 import/export 命令在运行时会打印黄色警告:prisma import / prisma1 export 命令未来将不再继续开发,建议改用数据库原生导入导出工具完成此类工作流。这一限制是项目自身在源码中声明的,使用时应以当前仓库版本的实际行为为准。
4.3 一套可落地的备份与复制工作流
综合全文,推荐的数据迁移实践路径如下:
- 导出:对源服务(如
devstage)执行prisma export(源码实现下为--path/-p指定输出 zip,或省略以生成时间戳命名文件),得到包含nodes、lists、relations三个子目录的 zip; - 核对:用数据导出得到的 NDF 结构作为模板,检查目标服务所需的数据(保持 schema 一致);
- 导入:对目标服务(如
prodstage)执行prisma import --data <导出的zip>;若中途中断,重新执行同一条命令即可借助state.json从断点继续; - 注意幂等性:切勿对同一服务重复执行同一份数据的导入,否则会因重复插入相同
id的节点产生未定义行为; - 善用 CLI 校验:当数据由人工编写或来自第三方时,优先走 CLI 导入以触发 Validator.ts 的字段、类型与枚举校验,把错误拦截在上传之前。
4.4 延伸阅读
- 01-Data-Import.md:数据导入命令与 API 的原始文档;
- 02-Data-Export.md:数据导出命令与 API 的原始文档;
- 03-Normalized-Data-Format.md:NDF 格式规范;
- 源码:import/index.ts、Importer.ts、Validator.ts、export/index.ts、Exporter.ts;
- 参考样例:fixtures/basic/types.graphql、fixtures/basic/import 目录、export/download/nodes/000001.json。