Prisma 数据导出完整指南：CLI 命令与原生 Export API 实战

后端数据库GraphQL【免费下载链接】prisma1 Database Tools incl. ORM, Migrations and Admin UI (Postgres, MySQL MongoDB) [deprecated]项目地址https://gitcode.com/gh_mirrors/pr/prisma1点击查看免费下载导读本文围绕 Prisma 服务Prisma 1.x的**数据导出Data Export**能力展开系统讲解两种导出途径prisma exportCLI 命令与 HTTP 原生导出 API。读完本文你将掌握 NDFNormalized Data Format规范化数据格式导出数据的组织方式、prisma export的完整用法与输出产物结构、导出 API 的请求/响应协议与基于游标cursor的分页续传机制并理解 CLI 在底层如何调用导出 API、服务端如何分页取数与控制 10 MB 响应上限。导出的 NDF 数据可直接用于 数据导入非常适合为dev等测试环境批量灌入测试数据。导出的两种途径与共同前提在 Prisma 中导出数据既可以走 CLI也可以直接调用服务端暴露的原始导出 API。两种方式产出的数据都是 JSON 格式并且统一遵循 NDF——这是 Prisma 内部定义的中间数据格式其完整结构说明见 Normalized Data Format (NDF)。由于导出数据是 NDF它可以直接导入到一个schema 完全相同的服务中。这一点在需要为某个服务准备测试数据时特别有用例如在dev阶段复制一份生产数据或构造好的数据到测试服务。方式一使用 CLI 导出prisma export命令与选项Prisma CLI 提供prisma export命令官方命令参考见 prisma export。文档中描述其接受一个选项--export-path短写-e指定一个.zip文件路径CLI 会创建该压缩包并把导出数据存放在其中。实际命令实现中export/index.ts参数名为--path短写-p描述为 “Path to export .zip file”此外还支持--env-file-e注入.env环境变量与--project指定 Prisma 定义文件路径。两个版本对应关系需要读者留意早期文档写作时选项名为--export-path/-e当前仓库 CLI 实现中导出路径 flag 为--path/-p、环境文件 flag 为--env-file/-e使用时请以你安装版本的prisma export --help为准。用法示例# 导出到默认文件名 export-timestamp.zip prisma export # 导出到指定文件 mydata.zip prisma export --path mydata.zip若未指定路径CLI 会自动生成默认文件名export-ISO 时间戳.zip如果给定的路径没有.zip后缀实现会自动补上见 export/index.ts。命令成功后还会提示后续导入方式Exported service to exportPath You can import it to a new service with $ prisma import --data exportPathCLI 相比原始 API 的优势文档明确指出CLI 底层使用的正是下一节介绍的导出 API源码中Exporter.download()通过client.download()调用服务端导出端点见 Client.ts。使用 CLI 的主要好处有三点复用 CLI 的认证机制无需手动在请求头中携带认证 tokenCLI 会通过definition.getToken(serviceName, stage)自动取得并在内部请求中附带见 export/index.ts直接落盘下载到的数据由 CLI 直接写入文件系统游标管理当一次响应装不下全部数据时CLI 会自动用返回的游标发起后续请求直到全部取完手动调用 API 则需要自己多次请求并逐次调整游标。输出格式三类目录导出的数据采用 NDFCLI 会将其组织到三个以 NDF 类型命名的目录中nodes/存放节点标量字段数据lists/存放节点的标量列表字段数据relations/存放通过关系字段连接两个节点的关系数据从源码看Exporter.download()会先创建这三个目录然后依次下载nodes、lists、relations三类数据每个响应写成一个带序号前缀的 JSON 文件如000001.json最后用archiver打包成 zip 并清理临时目录见 Exporter.ts。每个文件的 JSON 结构为{valueType: 类型, values: [...]}与 NDF 规范一致。方式二使用原生导出 API端点与请求格式原始导出 API 暴露在服务 HTTP 端点的/export路径下例如http://localhost:60000/my-app/dev/export本地开发服务https://database.prisma.sh/my-app/prod/exportPrisma Cloud 托管服务该端点接收POST 请求一次请求最多能下载10 MB的 NDF JSON 数据。必须在 HTTP 的Authorization请求头中携带你的认证 token否则请求无法通过鉴权。请求体是一个 JSON 对象包含fileType与cursor两个字段{ fileType: nodes, cursor: { table: 0, row: 0, field: 0, array: 0 } }其中fileType取值为nodes、lists、relations之一对应 NDF 的三种值类型cursor中的table、row、field、array四个值描述从数据库的哪个偏移位置开始导出数据。响应中的新游标与完成判定每次导出请求的响应都会返回一个新的cursor它只有两种状态已终止未满如果table、row、field、array四个值全部为-1表示本次导出已经全部完成未终止已满如果四个值中任意一个不是-1表示本次响应已经达到 10 MB 上限此时直接把返回的cursor作为下一次导出请求的游标输入继续取剩余数据。需要说明的是field与array两个游标维度在当前仓库的服务器实现中为占位字段服务端内部游标实际只维护table与row见 ImportExport.scala序列化响应时若table与row均为-1导出完成则field、array输出-1否则输出0见同文件MyJsonProtocol.cursorWrites第 88-93 行。服务端分页与大小控制的实现原理从源码可以进一步理解 10 MB 上限与游标分页的底层逻辑见 BulkExport.scala每类数据nodes/lists/relations都会把对应表模型列表打上索引构成table维度每个表内的数据按row偏移分页读取单页取first 1000条fetch()方法中的QueryArguments(skip row, first 1000, ...)序列化时累计 JSON 字节数一旦超过maxImportExportSize就标记isFull true并返回当前游标isLimitReached与serializeDataItems第 133-146 行。生产环境中maxImportExportSize 1000000即约 10 MB见 ApiDependencies.scala测试环境则缩小为 1000 以便快速验证当isFull false且当前表已取完时游标会table 1、row 0跳到下一张表cursorAtNextModel所有表都取完后返回Cursor(-1, -1)表示终止resForCursor第 38-47 行。CLI 端则通过“四个游标值求和 0就继续请求”的循环条件自动翻页Exporter.ts。curl 示例下面是文档给出的一个导出nodes类型数据的curl示例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注意上例中的 JWT 是文档示例中的演示 token实际使用必须替换为你自己服务的有效认证 token。将占位符泛化后通用形式如下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其中__SERVICE_ENDPOINT__形如http://localhost:60000/my-app/dev__NDF_TYPE__取nodes、lists、relations__TABLE__、__ROW__、__FIELD__、__ARRAY__填入游标偏移值首次请求全为0后续请求使用上一次响应的游标值。导出数据与 NDF 的对应关系了解 NDF 有助于理解导出产物与 API 响应的数据结构。NDF 是 Prisma 服务导入导出使用的中间 JSON 数据格式由valueType与values两个键构成详细规范见 Normalized Data Format (NDF)nodesvalues内每个对象是{_typeName: SDL 类型名, id: 节点 id, 标量字段: 值, ...}对应nodes/目录中的文件listsvalues内每个对象是{_typeName: ..., id: ..., 标量列表字段: [值, ...]}对应lists/目录中的文件relationsvalues内每个元素是一个恰好含两个对象的数组[{_typeName: ..., id: ..., fieldName: ...}, {...}]表示通过关系字段连接两个节点对应relations/目录中的文件。因此使用prisma export导出的 zip 解压后即为这三个目录的 NDF JSON 文件它们可以被prisma import --data 文件或导入 API 原样消费。注意事项关系型数据库是唯一受支持的导出目标当前仓库的 CLI 实现对documentMongoDB类型服务会直接报错提示“Export is not yet supported for document stores”建议改用 MongoDB 原生的mongodump等导出工具见 export/index.ts废弃状态提醒CLI 同时会输出警告prisma export命令未来不会再继续开发建议数据量较大的迁移/备份场景使用 MySQL 的mysqlimport、Postgres 的pg_restore等数据库原生导出导入工具同见 export/index.ts认证是硬性要求直接调用导出 API 时必须携带Authorization: Bearer token否则请求会被拒绝10 MB 响应上限一次 API 请求最多返回约 10 MB 数据超出部分需用返回的游标续传CLI 已自动处理该逻辑手动调用 API 时必须自行循环。赞分享后端数据库GraphQL【免费下载链接】prisma1 Database Tools incl. ORM, Migrations and Admin UI (Postgres, MySQL MongoDB) [deprecated]项目地址https://gitcode.com/gh_mirrors/pr/prisma1点击查看免费下载相关推荐Prisma 数据导出实战CLI prisma export 命令与原始 Export API 完整指南Prisma 数据导出实战CLI prisma export 命令与原始 Export API 完整指南 本指南围绕 Prisma 服务的数据导出能力展开覆后端数据库GraphQLPrisma 数据导出完全指南CLI 命令与原始 Export API 实战解析Prisma 数据导出完全指南CLI 命令与原始 Export API 实战解析 本篇技术指南围绕 Prisma 服务的数据导出Data Export能力后端数据库GraphQLPrisma 数据导出完全指南CLI 命令与原生 Export API 实战基于 NDF 格式Prisma 数据导出完全指南CLI 命令与原生 Export API 实战基于 NDF 格式 本指南系统讲解 Prisma 服务数据导出的两种官方途径—后端数据库GraphQL创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考