Prisma 服务器升级指南从通用准备流程到 1.7/1.8 版本迁移实战【免费下载链接】prisma1 Database Tools incl. ORM, Migrations and Admin UI (Postgres, MySQL MongoDB) [deprecated]项目地址: https://gitcode.com/gh_mirrors/pr/prisma1在 Prisma 的生命周期中服务器版本升级是一项需要谨慎对待的运维工作它可能涉及服务配置文件prisma.yml的结构调整、CLI 行为变化、Management API 端点变更等多个层面。本文以 Prisma 官方升级指南01-Overview.md为骨架完整梳理升级前必须完成的通用准备流程并以此为基线深入 1.7、1.8 两次关键升级的实操细节——包括endpoint迁移、post-deploy hooks、认证机制切换、管理数据库重命名等。读完本文你将掌握一套先评估、再备份、后预演、最终迁移的 Prisma 服务器升级方法论并能独立完成从旧版prisma.yml到新版结构的迁移。升级前的通用准备三步必做清单官方升级指南明确指出在升级 Prisma 服务器之前必须先遵循这里给出的通用指令再结合目标版本对应的专属升级说明即下文将展开的 1.7 / 1.8 升级指南。整个升级流程可以概括为三个步骤阅读发布说明、备份数据、预演测试。第一步通读两个版本之间的所有 Release Notes在开始升级前需要通读从当前版本到目标版本之间所有版本的发布说明Release Notes逐条评估哪些变更会影响你和你的项目。常见的影响面包括服务配置结构变更例如prisma.yml的属性增删CLI 命令的弃用或行为变化例如prisma local系列命令的弃用API 端点或认证方式的变化例如 Management API 路径调整。如果对某个变更的影响范围不确定不要盲目跳过——先查阅变更详情再决定是否需要在升级前对项目做相应的适配。对应到本仓库1.7 与 1.8 的升级指南就是按版本评估影响的两个典型范例详见 升级到 1.7 与 升级到 1.8。第二步为所有服务执行prisma export数据备份在开始迁移之前必须为所有服务执行prisma export创建数据备份。备份方式有两种选择使用 Prisma 自带的数据导出能力对每个服务运行prisma export将数据导出为标准化格式Normalized Data FormatNDF的.zip文件使用数据库自身的备份特性如果数据库如 MySQL、Postgres、MongoDB提供了原生的备份方案也可以作为替代。关键不在于备份过而在于备份可用。官方指南特别强调两点验证要求验证备份确实包含全部数据验证恢复流程可用——即prisma import或数据库原生恢复能够成功执行。只有可恢复的备份才是有效备份否则在升级失败回滚时将会面临数据丢失风险。第三步在 Staging 环境进行升级预演强烈建议先在预发布staging环境对升级流程做一次完整试运行目的有两个熟悉整个升级流程避免在生产环境首次操作时踩坑验证升级结果是否正常将升级后的 staging 环境跑完整个测试套件并执行贴近真实业务的重型查询queries与变更mutations确认 API 行为与升级前一致。预演通过后再以同样的步骤操作生产环境可显著降低升级风险。升级到 Prisma 1.7prisma.yml结构重构与 CLI 变更1.7 是 Prisma 历史上一次影响深远的升级它重构了服务配置结构、调整了 CLI 行为并引入了新的部署后钩子机制。好在这一版本的所有变更都是向后兼容的不升级也不影响现有服务继续运行且CLI 会尽量自动帮助完成所需的配置迁移。1.7 引入的术语变更升级到 1.7 后官方术语发生了变化文档、配置与日常沟通中需要注意旧术语新术语Prisma ClusterPrisma 集群Prisma ServerPrisma 服务器Development Cluster开发集群Prisma Sandbox新 YAML 结构service/stage/cluster合并为endpoint1.7 对prisma.yml的根属性做了较大调整官方升级指南列出的变更点如下移除service、stage、cluster三个属性新增endpoint属性用一个 URL 编码原来三个属性的全部信息新增post-deploy属性即部署后钩子详见下文移除disableAuth属性——如果不需要 Prisma API 认证直接省略secret属性即可移除schema属性——注意CLI 默认不再自动下载Prisma API 的 GraphQL schema通常命名为prisma.graphql如需获取 schema必须通过配置 post-deploy hook 来实现。关于新版prisma.yml的完整根属性说明datamodel、endpoint、secret、subscriptions、seed、custom、hooks可参考 prisma.yml YAML 结构参考。示例本地部署的prisma.yml迁移迁移前旧结构service: myservice stage: dev cluster: local datamodel: datamodel.graphql迁移到 Prisma 1.7 后endpoint: http://localhost:4466/myservice/dev datamodel: datamodel.graphql可以看到服务名myservice与 stagedev被编码进了 endpoint 的路径段而本地服务器的地址http://localhost:4466取代了cluster: local。示例部署到云端 Prisma Sandbox 的prisma.yml迁移迁移前旧结构service: myservice stage: dev cluster: public-crocusraccoon-3/prisma-eu1 datamodel: datamodel.graphql迁移到 Prisma 1.7 后endpoint: https://eu1.prisma.sh/public-crocusraccoon-3/myservice/dev datamodel: datamodel.graphql在 Prisma Cloud 场景下endpoint 的组成部分为https://server/workspace/service/stage其中eu1.prisma.sh是 Prisma 云服务器地址public-crocusraccoon-3是 Prisma Cloud 工作区Workspace的随机标识。两种场景下 CLI 的迁移行为不同如果你的 API 部署在 Prisma Cloud 服务器上CLI 会自动修改prisma.yml写入新的endpoint同时移除service、stage、cluster如果 API不是部署在 Prisma Cloud 上CLI 只会打印警告并给出手动更新提示。default服务名与defaultstage 的省略规则为方便使用1.7 引入了两个特殊值——default。当 endpoint 路径中的服务名与stage恰好都是default时可以省略不写CLI 会自动推断。例如http://localhost:4466/default/default可以简写为http://localhost:4466/https://eu1.prisma.sh/public-helixgoose-752/default/default可以简写为https://eu1.prisma.sh/public-helixgoose-752/这一规则同样适用于 API 的/import与/export端点http://localhost:4466/default/default/import可以简写为http://localhost:4466/importhttps://eu1.prisma.sh/public-helixgoose-752/default/default/export可以简写为https://eu1.prisma.sh/public-helixgoose-752/export从源码层面看这一推断逻辑在 CLI 的 parseEndpoint.ts 中有明确实现service与stage在路径段不足时会被默认填充为default本地localhost/127.0.0.1、私有prisma.sh私有域与共享eu1.prisma.sh、us1.prisma.sh服务器也会被分别识别最终返回包含service、stage、clusterName等字段的结构化解析结果。部署后钩子Post Deployment Hooks1.7 新增了post-deploy hooks机制可以指定任意终端命令由 Prisma CLI 在prisma deploy执行完毕后自动运行。下面这个例子在部署后依次完成三件事打印Deployment finished下载.graphqlconfig.yml中db项目指定的 GraphQL schema调用.graphqlconfig.yml中配置的代码生成。# in database/prisma.yml hooks: post-deploy: - echo Deployment finished - graphql get-schema - graphql prepare由于 1.7 起 CLI不再自动下载prisma.graphql也不再自动执行代码生成上述 hook 配置就成了获取 schema 与触发 codegen 的标准手段。配套的.graphqlconfig.yml示例指定 schema 保存到generated/prisma.graphqlTypeScript 类型定义输出到generated/prisma.tsprojects: prisma: schemaPath: generated/prisma.graphql extensions: prisma: prisma.yml prepare-binding: output: generated/prisma.ts generator: prisma-ts对应的prisma.yml中的 hook 配置为hooks: post-deploy: - graphql get-schema --project prisma - graphql prepareCLI 变更一prisma local命令弃用改用 Docker 直接管理prisma local系列命令被弃用转而建议直接使用 Docker CLI 完成相关工作。prisma local曾为部分 Docker 工作流提供了便捷抽象在 1.7 中这些工作流都可以通过 Docker CLI 手动完成。在 Prisma 1.7 中运行prisma init时CLI 会生成一个docker-compose.yml指定两个 Docker 容器的镜像prisma将数据库转换为 GraphQL API 的 Prisma API 镜像db连接的数据库镜像例如mysql。生成的docker-compose.yml原始版本如下version: 3 services: prisma: image: prismagraphql/prisma:1.7 restart: always ports: - 4466:4466 environment: PRISMA_CONFIG: | managementApiSecret: my-server-secret-123 port: 4466 databases: default: connector: mysql # or postgres active: true host: db port: 3306 # or 5432 for postgres user: root password: prisma db: container_name: prisma-db image: mysql:5.7 restart: always environment: MYSQL_USER: root MYSQL_ROOT_PASSWORD: prisma注意PRISMA_CONFIG中以|起始的块标量语法它承载了 Prisma 服务器自身的全部配置。CLI 变更二与 Docker 上运行的 Prisma 服务器进行认证当 CLI 需要面向基于 Docker 的 Prisma 服务器部署和管理 API 时必须进行认证否则任何能访问服务器 endpoint 的人都可以随意修改你的 Prisma API。旧机制非对称基于公钥/私钥对。公钥随 Prisma 集群一起部署私钥存放在集群注册表中作为clusterSecretCLI 用它认证请求。1.7 新机制对称部署在 Prisma 服务器上的密钥与 CLI 使用的密钥完全相同。将密钥提供给 Prisma 服务器Docker 上运行的 Prisma 服务器通过docker-compose.yml中的managementApiSecret键接收密钥。执行docker-compose up -d部署服务器时密钥会被存储到服务器上之后 CLI 发出的每个请求如prisma deploy都需要用该密钥认证。示例version: 3 services: prisma: image: prismagraphql/prisma:1.7 restart: always ports: - 4466:4466 environment: PRISMA_CONFIG: | managementApiSecret: my-server-secret-123 port: 4466 databases: default: connector: mysql # or postgres active: true host: db port: 3306 # or 5432 for postgres user: root password: prisma db: container_name: prisma-db image: mysql:5.7 restart: always environment: MYSQL_USER: root MYSQL_ROOT_PASSWORD: prisma让 CLI 使用同一密钥认证请求需要通过PRISMA_MANAGEMENT_API_SECRET环境变量显式设置密钥。最简单的方式是使用.env文件Prisma CLI 会自动识别它。示例PRISMA_MANAGEMENT_API_SECRETmy-server-secret-123这样 CLI 就能用与服务器一致的密钥完成prisma deploy等操作。CLI 变更三--boilerplate选项移除改用graphql create1.7 中prisma init命令的--boilerplate选项被移除无法再基于 GraphQL boilerplate 项目一键引导整个 GraphQL 服务器。如需基于 boilerplate 引导 GraphQL 服务器改用 GraphQL CLI 的graphql create命令# 安装 GraphQL CLI npm install -g graphql-cli # 从交互式提示中选择 boilerplate ... graphql create myapp # ... 或通过 --boilerplate 直接指定 boilerplate 项目如 typescript-advanced graphql create myapp --boilerplate typescript-advanced常见错误prisma.yml should NOT have additional properties升级后若遇到如下报错Invalid prisma.yml file prisma.yml should NOT have additional properties.原因通常是prisma.yml中仍残留了 1.7 已移除的旧属性如service、stage、cluster、disableAuth、schema或包含了尚未被新版本 schema 接受的属性。解决思路是按 1.7 的新结构清理配置将三合一为endpoint删除disableAuth改为省略secret删除schema改用 post-deploy hook 下载 schema。升级到 Prisma 1.8Management API 与管理数据库调整1.8 的变更集中在部署流程与Prisma 服务器的设置与管理两个方向主要包括 Management API 端点变更、管理数据库 schema 重命名以及新增的migrations连接器设置。Management API/cluster迁移到/managementManagement API 负责服务部署并提供 Prisma 服务器的信息。变更点如下旧路径/cluster例如localhost:4466/cluster在 1.8 中不再可用新路径为/management例如localhost:4466/managementManagement API 暴露的 GraphQL API 中顶层字段clusterInfo更名为serverInfoclusterInfo被标记为已弃用并将在版本 1.10 中移除。如果升级后你的工具链仍在调用/cluster或clusterInfo需要同步更新为/management与serverInfo。管理数据库graphcoolschema 更名为managementPrisma 服务器会在所连接的数据库中创建一个专门的管理 schema用于存储服务与服务迁移的信息旧版本中该 schema 名为graphcool1.8 起默认使用management通过 Prisma 服务器配置中的managementSchema设置可以使用不同的 schema 名对于Postgres 连接器database与managementSchema两个设置都可以调整。使用 MySQL 时的配置示例将管理 schema 改回旧的graphcool名称version: 3 services: prisma: image: prismagraphql/prisma:1.8 restart: always ports: - 4466:4466 environment: PRISMA_CONFIG: | port: 4466 databases: default: connector: mysql host: https://example.com port: 3306 user: root password: prisma managementSchema: graphcool # default: management使用 Postgres 时的配置示例同时调整database与managementSchemaversion: 3 services: prisma: image: prismagraphql/prisma:1.8 restart: always ports: - 4466:4466 environment: PRISMA_CONFIG: | port: 4466 databases: default: connector: postgres host: https://example.com port: 5432 user: root password: prisma database: graphcool # default: prisma managementSchema: graphcool # default: management升级到 1.8 后若你从旧版沿用而来且希望保持数据库中的管理 schema 名称不变例如仍在用graphcool就需要像上面这样显式设置managementSchema: graphcool。新增migrations连接器设置1.8 为连接器新增了migrations设置为禁用迁移的连接器提前做好准备。示例version: 3 services: prisma: image: prismagraphql/prisma:1.8 restart: always ports: - 4466:4466 environment: PRISMA_CONFIG: | port: 4466 databases: default: connector: postgres host: https://example.com port: 5432 user: root password: prisma migrations: false # default: truemigrations: false通常用于已预置好数据库 schema 与存量数据的现有数据库一般配合 introspection数据库内省功能使用——1.8 开始为 Postgres 连接器引入了连接现有数据库的初步 alpha 支持MySQL 连接器后续也将支持同样的能力。这意味着在升级到 1.8 后如果你计划接入已有数据库需要根据实际情况评估是否关闭该连接的自动迁移。升级决策路线图把通用清单落到具体版本综合官方升级指南01-Overview.md与两次具体版本的升级说明一次完整的 Prisma 服务器升级可以按以下路线执行评估影响通读当前版本到目标版本之间所有 Release Notes对照 升级到 1.7 与 升级到 1.8 中的变更清单逐项确认是否影响你的prisma.yml、CLI 脚本或数据库配置备份数据对每个服务运行prisma export或使用数据库原生备份并验证prisma import恢复可行迁移配置将prisma.yml从旧结构迁移到新结构service/stage/cluster→endpoint必要时补充hooks.post-deploy同步更新docker-compose.yml中的服务器镜像版本与managementApiSecret同步认证与工具链将服务器密钥与PRISMA_MANAGEMENT_API_SECRET对齐若涉及 1.8将 Management API 调用从/cluster切换到/management并评估管理 schema 是否需要显式指定预演测试在 staging 环境完成升级跑完整测试套件与真实查询/变更确认无回归后再上线生产。如果升级涉及的是从 Graphcool 平台迁移到 Prisma 的场景而非 Prisma 版本间的升级可以进一步参考仓库中的 Graphcool 到 Prisma 迁移指南。小结升级 Prisma 服务器的成败往往不取决于升级动作本身而取决于升级前后的准备与验证。官方升级指南给出的三件事——通读 Release Notes 评估影响、用prisma export备份并验证可恢复、在 staging 环境完整预演——是任何版本升级都不应跳过的底线。而 1.7 与 1.8 两次升级则展示了配置迁移的典型形态prisma.yml的结构收敛三属性合一为endpoint、行为变化schema 不再自动下载、prisma local弃用、认证机制演进对称密钥managementApiSecret/PRISMA_MANAGEMENT_API_SECRET以及管理面调整/cluster→/management、clusterInfo→serverInfo、graphcool→management。按版本逐条对照变更、借助 CLI 的自动迁移能力、在预演中验证效果就能把版本升级的不可控因素降到最低。【免费下载链接】prisma1 Database Tools incl. ORM, Migrations and Admin UI (Postgres, MySQL MongoDB) [deprecated]项目地址: https://gitcode.com/gh_mirrors/pr/prisma1创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
