Prisma 服务配置文件 `prisma.yml` 完整指南：Overview、YAML 结构与变量机制

Prisma 服务配置文件prisma.yml完整指南Overview、YAML 结构与变量机制【免费下载链接】prisma1 Database Tools incl. ORM, Migrations and Admin UI (Postgres, MySQL MongoDB) [deprecated]项目地址: https://gitcode.com/gh_mirrors/pr/prisma1prisma.yml是每个 Prisma 服务的核心配置文件集中定义了服务名称、数据模型datamodel、部署目标cluster 与 stage、认证方式、事件订阅函数、数据种子seed等全部服务组件。本指南以 Prisma 1.x 服务配置参考文档为主体结合仓库中prisma-yml解析实现与 CLI 源码系统讲解prisma.yml的完整 YAML 结构、每一项属性的取值规则与默认行为以及${env:}、${self:}、${opt:}三类变量机制的底层工作方式。读完本文你将能够从零编写一份可部署、可复用的 Prisma 服务定义文件。prisma.yml是什么一个 Prisma 服务由多个组件构成服务名称、服务的数据模型datamodel、部署与认证信息、以及事件订阅函数的配置等。这些组件全部集中定义在服务的配置文件prisma.yml中因此它既是服务的身份证明也是 CLI 执行deploy、generate、seed等命令时的配置入口。从源码看CLI 通过 PrismaDefinition.ts 中的PrismaDefinitionClass加载并解析该文件它会调用readDefinition读取 YAML解析secret、datamodel、endpoint等字段并在加载后执行validate()校验如既未配置 secret 也未显式 disableAuth 时直接抛错这一点在 PrismaDefinition.test.ts 的throw when no secret or disable auth provided用例中有明确验证。如果当前目录找不到prisma.ymlCLI 会抛出Couldnt find prisma.yml file. Are you in the right directory?错误。一个完整的示例文件下面是一个典型的服务定义文件覆盖了prisma.yml支持的全部核心属性节选自 01-Overview--Example.md# REQUIRED # my-demo-app 是这个 Prisma 服务的名称 service: my-demo-app # REQUIRED # 该服务基于两个文件中的类型定义 # database/types.graphql 和 database/enums.graphql datamodel: - database/types.graphql - database/enums.graphql # OPTIONAL # 服务将部署到 local 集群。 # 注意若省略此选项CLI 会交互式询问部署到哪个集群 # 并把你的选择持久化写回这里。 cluster: local # REQUIRED # 该服务将部署到 dev 这个 stage stage: dev # OPTIONAL (default: false) # 是否需要对服务启用认证取决于 PRISMA_DISABLE_AUTH # 环境变量的取值。 disableAuth: ${env:PRISMA_DISABLE_AUTH} # OPTIONAL # 如果服务需要认证这里是用于签发 JWT 的密钥。 secret: # OPTIONAL # 部署完成后完整 GraphQL schema 的写入路径。 # 注意它是基于你的数据模型生成的。 schema: schemas/prisma.graphql # OPTIONAL # 该服务配置了一个事件订阅。对应的订阅查询位于 # database/subscriptions/sendWelcomeEmail.graphql。 # 订阅触发时指定的 webhook 会通过 HTTP 被调用。 subscriptions: sendWelcomeEmail: query: database/subscriptions/sendWelcomeEmail.graphql webhook: url: https://${self.custom:serverlessEndpoint}/sendWelcomeEmail headers: Authorization: ${env:MY_ENDPOINT_SECRET} # OPTIONAL # 指向一个包含 GraphQL 操作的 .graphql 文件 # 首次部署服务时会执行其中的操作。 seed: import: database/seed.graphql # OPTIONAL # 该服务仅定义了一个自定义变量被上方 subscription 的 # webhook 引用。 custom: serverlessEndpoint: https://bcdeaxokbj.execute-api.eu-west-1.amazonaws.com/dev该服务定义期望以下目录结构与之配套. ├── prisma.yml ├── database │ ├── subscriptions │ │ └── welcomeEmail.graphql │ ├── types.graphql │ └── enums.graphql └── schemas └── prisma.graphql注意上面示例中的两个细节secret字段留空表示该服务不配置签名密钥实际是否启用认证取决于disableAuth而disableAuth直接引用环境变量${env:PRISMA_DISABLE_AUTH}——这是将认证开关交给部署环境控制的常见做法。prisma.yml的根级属性一览根据 02-YAML-Structure.mdprisma.yml的根级属性如下属性必填类型作用service✅stringPrisma 服务的名称datamodel✅string 或 string 列表数据库模型、关系、枚举等类型的定义stage✅string服务部署到的 stage 名称cluster❌string部署目标集群名省略则交互式选择disableAuth❌boolean是否禁用端点认证secret❌string用于保护 API 端点的密钥schema❌string生成后的数据库 schema 写入路径subscriptions❌object事件订阅函数的配置seed❌object数据种子的导入/执行指令custom❌object自定义变量可被其他字段引用官方文档指出prisma.yml的精确结构由 JSON Schema 定义文档中链接到 graphcool-json-schema 仓库的schema.json。在仓库内PrismaDefinitionClass从prisma-json-schema包引入PrismaDefinition类型作为解析结果的类型约束。下面逐一展开每个属性的详细规则。service必填——服务名称service定义服务名称部署后它会反映在服务的端点endpointURL 中。命名必须满足只能包含字母数字字符、连字符-和下划线_必须以大写或小写字母开头最长 64 个字符。它期待一个字符串。例如service: hello-worldservice: My-DEMO_APP123datamodel必填——数据模型文件datamodel指向一个或多个包含类型定义的.graphql文件以 GraphQL SDL 编写。如果提供多个文件CLI 在部署时会简单地将它们的内容拼接起来。它期待一个字符串或字符串列表# 单个文件 datamodel: types.graphql# 多个文件部署时内容会被拼接 datamodel: - types.graphql - enums.graphql从实现上看PrismaDefinitionClass.getTypesString()会读取所有 datamodel 文件的完整内容并合并为typesStringCLI 后续基于该字符串完成类型解析与 schema 生成。stage必填——部署阶段stage定义服务的部署目标名称如dev、prod它期待一个字符串stage: dev也支持从环境变量读取stage: ${env:MY_STAGE}cluster可选——部署集群cluster指定服务部署到的集群引用的是全局注册表~/.prismarc中登记的集群。命名规则与service相同字母数字、连字符、下划线字母开头最长 64 字符。如果省略该属性CLI 会触发交互式集群选择并将选择结果写回prisma.yml。cluster: localdisableAuth可选——是否禁用认证disableAuth表示 Prisma 服务是否需要认证。如果设为true任何人都拥有数据库的完全读写权限请谨慎使用。默认值为false即默认启用认证。它期待一个布尔值disableAuth: true # 关闭认证生产环境极不推荐 disableAuth: false # 开启认证默认在 PrismaDefinition.test.ts 中load yml with disableAuth: true用例验证了该配置可以配合.env中的密钥正常加载。secret可选——JWT 签名密钥secret用于生成签署认证令牌JWT。如果服务启用了认证请求方需要在 HTTP 请求的Authorization头中附带由该密钥签发的令牌。密钥必须满足必须是 UTF-8 编码不能包含空格最长 256 个字符。它期待一个字符串不是字符串列表。如果希望配置多个密钥以便平滑轮换可以在同一个字符串中用逗号分隔逗号两侧的空格会被忽略# 单个密钥 secret: moo4ahn3ahb4phein1eingaep# 三个密钥逗号分隔空格被忽略 secret: myFirstSecret, SECRET_NUMBER_2,3rd-secret# 从环境变量读取 secret: ${env:MY_SECRET}从实现看PrismaDefinition.ts 加载定义后执行secrets.replace(/\s/g, ).split(,)——即先去除所有空白字符再按逗号切分成密钥数组这正是逗号分隔多密钥、空格被忽略规则的来源。认证时服务端会用任一已配置密钥校验 JWT从而支持无中断的密钥轮换。安全校验逻辑在测试中同样被覆盖throw when no secret or disable auth provided用例表明既没有secret又没有显式disableAuth: true时定义加载会直接报错。schema可选——生成 schema 的写入路径每次部署服务时CLI 都会基于数据模型生成服务的数据库 schema通常名为database.graphql其中包含数据模型中所有类型的 CRUD 操作定义。schema指定生成文件的存放路径如果不设置该属性CLI 将不会生成并保存数据库 schema。它期待一个字符串schema: database.graphqlschema: src/schemas/database.graphqlsubscriptions可选——事件订阅函数subscriptions用于定义服务的所有事件订阅函数。每个订阅至少需要两类信息订阅查询subscription query定义触发函数的事件以及 payload 形态webhook URL事件发生时通过 HTTP 调用的地址可选附加到请求上的若干 HTTP 头。它期待一个对象结构为query必填订阅查询文件的路径webhook必填webhook 的信息。若没有 HTTP 头可以直接把 URL 字符串赋给webhook否则webhook是包含url与headers的对象。# 无 HTTP 头webhook 直接写 URL 字符串 subscriptions: sendWelcomeEmail: query: database/subscriptions/sendWelcomeEmail.graphql webhook: https://bcdeaxokbj.execute-api.eu-west-1.amazonaws.com/dev/sendWelcomeEmail# 带两个 HTTP 头 subscriptions: sendWelcomeEmail: query: database/subscriptions/sendWelcomeEmail.graphql webhook: url: https://bcdeaxokbj.execute-api.eu-west-1.amazonaws.com/dev/sendWelcomeEmail headers: Authorization: ${env:MY_ENDPOINT_SECRET} Content-Type: application/jsonseed可选——数据种子数据库 seeding 是为服务填充测试数据的标准化方式。seed期待一个对象包含以下两个子属性之一import导入数据。可指向两种文件一个包含 GraphQL 操作的.graphql文件一个包含 NDFNormalized Data Format数据集的.zip文件。runseeding 时执行的 shell 命令用于import无法覆盖的更复杂场景原文档注明run当时尚未支持仓库中对应的 seed 命令实现位于 commands/seed/seed.ts 与 commands/seed/Seeder.ts。种子会在服务首次部署时隐式执行除非用--no-seed标志显式禁用。# 执行 .graphql 文件中的 seeding 变更 seed: import: database/seed.graphql# 导入 NDF 格式的 .zip 数据集 seed: import: database/backup.zip# seeding 时运行 Node 脚本 seed: run: node script.jscustom可选——自定义变量custom允许你定义任意希望在prisma.yml其他位置复用的值因此它没有预定义的结构。它期待一个对象可通过self变量源引用例如${self.custom.myVariable}custom: serverlessEndpoint: https://bcdeaxokbj.execute-api.eu-west-1.amazonaws.com/dev subscriptionQueries: database/subscriptions/ subscriptions: sendWelcomeEmail: query: ${self.custom:subscriptionQueries}/sendWelcomeEmail.graphql webhook: https://${self.custom:serverlessEndpoint}/sendWelcomeEmail使用变量动态替换配置值变量机制允许在prisma.yml中动态替换配置值详见 03-Using-Variables.md。引用方式是用${}包裹括号内先用冒号分隔变量源与变量名yamlKeyXYZ: ${src:myVariable} # src 为变量源见下文 otherYamlKey: ${src:myVariable, defaultValue} # 可提供默认值作为第二参数变量源共有三种环境变量、同一服务文件内的自引用、命令行选项。注意变量只能用于属性的值不能用于属性的键。仓库中的变量替换实现位于 Variables.ts它以RegExp(\\${([ ~:a-zA-Z0-9._\,\\-\\/\\(\\)]?)}, g)匹配变量语法并分别用envRefSyntax^env:、selfRefSyntax^self:、optRefSyntax^opt:识别三类变量源随后递归遍历 YAML 对象的所有字符串值完成替换。环境变量${env:...}引用环境变量时括号内由前缀env:加上环境变量名组成service: example stage: ${env:PRISMA_STAGE} cluster: ${env:PRISMA_CLUSTER} secret: ${env:PRISMA_SECRET} datamodel: database/datamodel.graphqlCLI 会按以下顺序从 3 个位置加载环境变量本地环境进程环境变量通过--dotenv参数指定的文件若省略--dotenv参数则加载同一目录下的.env文件。从源码看PrismaDefinition.ts 的load()方法中调用了dotenv.config({ path: envPath })完成.env/--env-file的加载而 PrismaDefinition.test.ts 中的load yml with secret and env var in .env、load yml with secret and env var等用例分别验证了从.env文件与进程环境变量读取${env:...}的行为。自引用${self:...}你可以递归引用同一prisma.yml文件中的其他属性值。括号内由前缀self:加上可选的目标属性路径组成若不指定路径变量值就是整个 YAML 文件内容。下面的例子中createCRMEntry订阅复用了sendWelcomeEmail的订阅查询并通过self引用共享 webhook 配置subscriptions: sendWelcomeEmail: query: database/subscriptions/createUserSubscription.graphql webhook: url: ${self.custom.serverlessEndpoint}/sendWelcomeEmail headers: ${self.custom.headers} createCRMEntry: query: ${self:functions.subscriptions.sendWelcomeEmail.query} webhook: url: ${self.custom.serverlessEndpoint}/createCRMEntry headers: ${self.custom.headers} custom: serverlessEndpoint: https://bcdeaxokbj.execute-api.eu-west-1.amazonaws.com/dev headers: Authorization: Bearer wohngaeveishuomeiphohph1ls注意self引用既可以写成点路径形式如${self.custom.serverlessEndpoint}也可以写成冒号形式如${self.custom:serverlessEndpoint}两种语法都会被变量解析器接受这也解释了 Overview 示例中的写法。自引用的解析逻辑同样由 Variables.ts 的populateObject/populateProperty实现它递归遍历对象、按属性路径取值后回填到引用位置。命令行选项${opt:...}你还可以引用执行prisma命令时传入的 CLI 选项。括号内由前缀opt:加上 CLI 选项名组成例如# 引用 CLI 传入的选项示意 stage: ${opt:stage}该机制同样由Variables.ts中的optRefSyntax支持构造Variables实例时传入的options即 CLI 解析后的参数对象会作为取值来源${opt:xxx}在运行时被替换为对应命令行参数的值。从源码看prisma.yml的加载与校验链路将上述内容串联起来一份prisma.yml在 CLI 中的完整处理链路如下定位文件PrismaDefinitionClass.load()优先处理--project指定的路径否则在当前目录查找prisma.yml找不到则报错退出加载环境变量通过dotenv.config加载--env-file/--dotenv指定的文件或同目录.env解析 YAML 与替换变量readDefinition读取 YAML 后由Variables类按env:、self:、opt:三种语法完成全部${...}替换类型化与校验解析结果映射为prisma-json-schema的PrismaDefinition类型随后validate()执行必填项与安全相关校验例如缺失secret且未显式disableAuth时报错派生运行时信息从解析结果计算secrets数组按逗号切分、去除空白、typesString拼接全部 datamodel 文件内容以及endpoint等供deploy、generate、token、seed等命令消费。这份配置文件的解析与校验逻辑集中在 cli/packages/prisma-yml/src 目录下其中 PrismaDefinition.ts 与 Variables.ts 是最核心的两个文件CLI 侧对配置的实际消费可参见 commands/deploy/deploy.ts、commands/seed/seed.ts 与 commands/generate/generate.ts。小结prisma.yml是 Prisma 服务定义的总入口service、datamodel、stage为必填项其余属性按需配置认证安全由disableAuth与secret共同决定显式关闭认证disableAuth: true会让数据库完全暴露务必谨慎多密钥逗号分隔机制支持无中断轮换事件订阅通过subscriptions.graphql订阅查询 webhook 实现custom与seed分别解决配置复用与数据初始化问题三类变量源${env:...}、${self:...}、${opt:...}让同一份prisma.yml可以适配不同环境与不同部署参数变量只能在属性值中使用。【免费下载链接】prisma1 Database Tools incl. ORM, Migrations and Admin UI (Postgres, MySQL MongoDB) [deprecated]项目地址: https://gitcode.com/gh_mirrors/pr/prisma1创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考