后端数据库GraphQL【免费下载链接】prisma1 Database Tools incl. ORM, Migrations and Admin UI (Postgres, MySQL MongoDB) [deprecated]项目地址https://gitcode.com/gh_mirrors/pr/prisma1点击查看免费下载导读prisma import是 Prisma CLI 提供的核心数据导入命令用于将标准化格式NDFNormalized Data Format的数据批量写入 Prisma 服务对应的数据库Postgres、MySQL。本文以 prisma import 命令参考 为骨架结合 Data Import 章节、NDF 规范 以及 CLI 源码 Importer.ts 与 Validator.ts完整讲解命令用法、导入数据结构、CLI 底层执行流程与校验规则并给出可复制的 NDF 示例与 curl 调用方式。读完本文你将能独立完成从组织 NDF 数据目录到执行prisma import的完整数据导入流程。命令概述prisma importprisma import用于将数据导入到 Prisma 服务对应的数据库中。导入数据必须按照 NDFNormalized Data Format标准化数据格式组织这是导入流程的硬性前提。更完整的背景可阅读 Data Import 章节。在 CLI 源码中该命令的定义位于 cli/packages/prisma-cli-core/src/commands/import/index.ts其topic为import描述为 Import data into a service。实际执行导入工作的是Importer类见 Importer.ts它负责解压、文件发现、数据校验、分块上传与断点续传状态管理。用法prisma import [flags]Flags命令行参数Flag简写类型必填说明--data-dPATH是指向包含导入数据NDF的 zip 文件或目录的路径--env-file-eENV-FILE否用于注入环境变量的.env文件路径从源码 index.ts 可以看到命令实际还支持一个未写入命令参考文档的隐藏参数Flag简写类型必填说明--project-pPATH否Prisma definition 文件prisma.yml的路径命令执行时会依次完成以下工作对应 index.ts 的run()加载prisma.yml定义文件若指定了--env-file则先注入对应环境变量从定义中解析出service名称与stage如dev获取目标 cluster 并设置为当前活跃 cluster检查--data指向的路径是否存在、是否为目录或以.zip结尾否则抛出错误通过this.definition.getToken(serviceName, stage)取得认证令牌后调用importer.upload()执行上传。需要特别留意的是源码中的两处警告逻辑index.ts若目标服务databaseType为document即 MongoDB 等文档型存储命令会直接抛出异常提示Import is not yet supported for document stores并建议改用数据库原生的导入功能如mongorestore对于关系型数据库Postgres/MySQL命令会打印一条警告说明prisma import后续将不再继续开发建议未来的工作流改用数据库原生导入工具。导入流程总览数据导入整体分两步图示来自 Data Import 章节-------------- ---------------- ------------ | SQL | | | | | | MongoDB | (1) transform | NDF | (2) chunked upload | Prisma | | JSON | --------------- | | ------------------- | | | | | | | | -------------- ---------------- ------------步骤 1transform将具体数据源MySQL、MongoDB、JSON 等转换为 NDF。这一步需要手动完成——截至当前仓库对应版本CLI 尚未内置从具体数据源直接转换的能力官方计划见仓库历史 issue是在未来版本中让 CLI 直接支持从这些数据源导入。步骤 2chunked upload把 NDF 数据分块上传到 Prisma 服务。可以通过底层 raw import API 手动上传也可以直接用prisma import命令完成。使用 CLI 相比直接调用 raw import API 有以下优势原文档明确列出一次上传多个文件无需逐个文件单独上传直接复用 CLI 的认证机制无需手工在 HTTP 头中附带认证令牌支持暂停与恢复进行中的导入断点续传预留了从 MySQL、MongoDB、Firebase 等数据源直接导入的能力当时尚未开放。关于幂等性与数据校验的重要警告原文档以醒目的警告框强调了两点直接关系到导入安全性导入操作不具备幂等性每次运行prisma import都只会向服务追加数据永远不会更新既有节点。因此对同一份数据集重复导入会导致未定义行为例如用相同id导入同一节点两次很可能破坏服务。数据校验raw import API 对导入数据不做任何校验而通过 CLI 导入时会执行基础校验详见下文CLI 源码解析。导入非法数据会导致未定义行为服务维护者有责任确保导入数据的合法性。一个推荐的校验技巧导入前先对数据模型完全一致的服务执行一次 导出检查导出的数据结构作为构造合法导入数据的参照。另外NDF 文件在上传时按三种类型组织每种类型可上传任意数量的文件但单个文件大小不应超过 10 MB。理解 NDF导入数据的中间格式NDF 是 Prisma 服务导入/导出使用的中间数据格式本质上是遵循特定结构的 JSON。完整规范见 Normalized Data Format (NDF)。NDF 的三种 valueType数据按值类型拆分成三类Nodes节点的标量字段数据即数据库中的记录Lists节点的列表字段数据Relations通过关系字段连接两个节点的数据。所有 NDF JSON 文档均为包含两个键的对象valueType标识文档的值类型取值为nodes、lists或relationsvalues实际数据数组结构随 valueType 不同而变化。下面以这个数据模型为例展开三种结构示例源自 NDF 规范文档type User { id: String! unique firstName: String! lastName: String! hobbies: [String!]! partner: User }nodes 结构valueType为nodes时values数组中每个对象的结构为{ valueType: nodes, values: [ { _typeName: STRING, id: STRING, scalarField1: ANY, ..., scalarFieldN: ANY }, ... ] }其中_typeName与id均为字符串_typeName对应数据模型中的 SDL 类型名scalarFieldX是该类型的标量字段名。例如导入两个User节点的标量值{ valueType: nodes, values: [ {_typeName: User, id: johndoe, firstName: John, lastName: Doe}, {_typeName: User, id: sarahdoe, firstName: Sarah, lastName: Doe} ] }lists 结构valueType为lists时对象结构为{ valueType: lists, values: [ { _typeName: STRING, id: STRING, scalarListField: [ANY] }, ... ] }注意与标量列表字段不同每个对象只能为一个列表字段提供值。例如导入两个User节点的hobbies列表字段{ valueType: lists, values: [ {_typeName: User, id: johndoe, hobbies: [Fishing, Cooking]}, {_typeName: User, id: sarahdoe, hobbies: [Biking, Coding]} ] }relations 结构valueType为relations时values数组中的每个元素本身是一个二元组恰好包含两个节点的数组用于描述一条关系{ valueType: relations, values: [ [ { _typeName: STRING, id: STRING, fieldName: STRING }, { _typeName: STRING, id: STRING, fieldName: STRING } ], ... ] }每个节点的_typeName、id、fieldName均为字符串fieldName指向该类型上的关系字段名。例如通过partner关系字段连接两个User节点{ valueType: relations, values: [ [ { _typeName: User, id: johndoe, fieldName: partner }, { _typeName: User, id: sarahdoe, fieldName: partner } ] ] }输入格式如何组织导入数据目录使用 CLI 导入时NDF 文件必须按类型放入三个固定目录名下nodes、lists、relations。命名规则来自 Data Import 章节NDF 文件是遵循特定结构的 JSON 文件因此文件名必须以.json结尾放入对应目录后.json文件需要从 1 开始递增编号例如1.json文件名可以带任意数量的前导零例如01.json或0000001.json均可。原文档给出的完整示例目录结构. ├── data │ ├── lists │ │ ├── 0001.json │ │ ├── 0002.json │ │ └── 0003.json │ ├── nodes │ │ ├── 0001.json │ │ └── 0002.json │ └── relations │ └── 0001.json ├── datamodel.graphql └── prisma.ymldata目录承载全部待导入数据其中所有.json文件都符合 NDF。在终端执行prisma import --data data该目录结构在仓库的测试夹具中也有真实对应物cli/packages/prisma-cli-core/src/commands/import/fixtures/basic/import 下就包含lists/000001.json、nodes/000001.json、relations/000001.json三个示例文件并附带了import.zip与state.json后者即断点续传状态文件。以其中的nodes/000001.json为例其开头部分为{ valueType: nodes, values: [ { _typeName: Post, id: 400, title: Quas dolores earum corporis aut voluptatibus dicta voluptatem., state: Published }, ... ] }而relations/000001.json则展示了真实的关系元组写法——每个元组是一个二元数组两个端点各自携带_typeName、id与fieldName{ valueType: relations, values: [ [ {_typeName: Post, id: 400, fieldName: comments}, {_typeName: Comment, id: 450, fieldName: post} ], ... ] }CLI 底层实现解析导入是如何执行的prisma import的实际导入逻辑封装在 Importer.ts 的Importer类中其upload()方法第 95-208 行完整展现了执行链路解压unzip若--data指向的是 zip 文件使用adm-zip将其解压到工作目录下的.import/目录若本身就是目录则直接使用。发现文件getFiles通过globby分别扫描nodes/、lists/、relations/三个子目录下的所有*.json文件。校验validateFiles对三类文件逐一调用Validator进行 NDF 结构校验详见下文。分块上传依次上传nodes、lists、relations。每个文件通过client.upload(serviceName, stage, file, token, workspaceSlug)上传若响应中包含errorscheckForErrors()会抛出异常终止导入。断点续传state上传完每个文件后将该文件的编号写入state.jsonsaveState下次重新运行时会读取状态跳过编号小于等于已记录状态的文件并打印Skipping file ... (already imported)。三类文件分别记录nodes、lists、relations三个计数见State接口与defaultState全部完成后重置为默认状态。清理导入完成或发生未捕获异常时若数据源是 zip删除临时解压目录.import/。从源码可确认的关键约束Importer构造时会先检查导入路径是否存在Import path ... does not exist文件名编号通过正则/.*?(\d)\.json/提取getNumber这也解释了为何文件必须命名为数字编号的.json。数据校验规则Validator 做了什么CLI 的基础校验由 Validator.ts 的Validator类实现。它接收服务的数据模型 SDLtypesString在命令中来自this.definition.typesString通过graphql的parse解析 AST 后执行一系列校验主要包括类型与 id每个对象必须有_typeName且存在于数据模型中checkTypeName必须有字符串类型的idcheckIdField。必填字段nodes数据必须包含所有必填的非关系标量字段checkRequiredFields。未知字段对象中不允许出现数据模型之外的字段checkUnknownFields允许的键为_typeName、id、createdAt、updatedAt加已知字段。标量类型校验内置了ID、String、Int、Float、DateTime、Boolean、Json的类型验证器validators字段见第 40-65 行其中DateTime通过正则校验YYYY-MM-DDTHH:mm:ss.SSSZ格式数据模型中的枚举类型会被收集后生成对应的枚举值校验器makeEnumValidators。列表语义nodes数据中不允许出现列表字段值lists数据中不允许出现单值标量validateValue。关系元组relations的每个元组必须是恰好含 2 个节点的数组每个节点都需校验_typeName与id且至少一个端点必须提供fieldName且该字段必须存在于数据模型中validateRelationTuple/checkFieldName。任何一条不满足都会抛出带详细信息的错误。这正是 CLI 导入优于 raw API 之处导入非法数据前就能被拦下。使用 raw import API 导入如果不想使用 CLI也可以直接向服务的 HTTP 端点发送请求调用底层导入 API。/import路径挂在服务端点上例如http://localhost:60000/my-app/dev/import本地https://database.prisma.sh/my-app/prod/import云端单次请求可上传的 NDF JSON 数据最多 10 MB且必须在 HTTP 的Authorization头中携带你的认证令牌JWT。原文档给出的curl示例上传valueType为nodes的数据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模板使用占位符curl __SERVICE_ENDPOINT__/import \ -H Content-Type: application/json \ -H Authorization: Bearer __JWT_AUTH_TOKEN__ \ -d {valueType:__NDF_TYPE__,values: __DATA__ } \ -sSv其中__NDF_TYPE__替换为nodes、lists或relations之一。需要再次强调raw API不做任何数据校验请自行保证 NDF 合法性。相关资源prisma import 命令参考Data Import 章节Normalized Data Format (NDF) 规范Data Export 章节数据导入的前置参照命令入口源码cli/packages/prisma-cli-core/src/commands/import/index.ts导入执行器cli/packages/prisma-cli-core/src/commands/import/Importer.tsNDF 校验器cli/packages/prisma-cli-core/src/commands/import/Validator.ts测试夹具与真实 NDF 数据cli/packages/prisma-cli-core/src/commands/import/fixtures/basic/import赞分享后端数据库GraphQL【免费下载链接】prisma1 Database Tools incl. ORM, Migrations and Admin UI (Postgres, MySQL MongoDB) [deprecated]项目地址https://gitcode.com/gh_mirrors/pr/prisma1点击查看免费下载相关推荐Prisma 数据导入完全指南NDF 格式、prisma import 命令与原始导入 APIPrisma 数据导入完全指南NDF 格式、prisma import 命令与原始导入 API Prisma 服务的数据导入Data Import是将外部后端数据库GraphQLPrisma 数据导入完全指南NDF 格式、prisma import 命令与原始导入 API 实战Prisma 数据导入完全指南NDF 格式、 prisma import 命令与原始导入 API 实战 本指南以 Prisma 1.4 官方文档《Data I后端数据库GraphQLPrisma 数据导入完全指南NDF 格式、prisma import 命令与原生导入 API 实战Prisma 数据导入完全指南NDF 格式、prisma import 命令与原生导入 API 实战 数据迁移是数据库服务上线前最关键的环节。Prisma 提后端数据库GraphQL上一篇OpenMed 安全架构深度解析无PHI日志与提示注入防护的完整设计下一篇Lenovo Legion Toolkit 完整指南3 步接管拯救者笔记本的性能调校创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
