Prisma 服务数据导入导出实战:NDF 格式、prisma import/export 命令与原始 HTTP API 全解析

原创2026-09-22 19:46:561,980 阅读
文章标签:后端数据库GraphQL

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/import
  • https://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):

  1. makeDirs() 在本地 .export/ 临时目录下创建 nodes/、lists/、relations/ 三个子目录;
  2. 依次调用 downloadFiles('nodes', ...)、downloadFiles('lists', ...)、downloadFiles('relations', ...);
  3. zipIt() 用 archiver 把三个目录打包成 zip 写入目标路径;
  4. 清理临时目录 .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/export
  • https://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 一套可落地的备份与复制工作流

综合全文,推荐的数据迁移实践路径如下:

  1. 导出:对源服务(如 dev stage)执行 prisma export(源码实现下为 --path/-p 指定输出 zip,或省略以生成时间戳命名文件),得到包含 nodes、lists、relations 三个子目录的 zip;
  2. 核对:用数据导出得到的 NDF 结构作为模板,检查目标服务所需的数据(保持 schema 一致);
  3. 导入:对目标服务(如 prod stage)执行 prisma import --data <导出的zip>;若中途中断,重新执行同一条命令即可借助 state.json 从断点继续;
  4. 注意幂等性:切勿对同一服务重复执行同一份数据的导入,否则会因重复插入相同 id 的节点产生未定义行为;
  5. 善用 CLI 校验:当数据由人工编写或来自第三方时,优先走 CLI 导入以触发 Validator.ts 的字段、类型与枚举校验,把错误拦截在上传之前。

4.4 延伸阅读

登录后查看全文
prisma1