Prisma CLI 使用指南：服务初始化、prisma.yml 配置与 HTTP 代理（基于 prisma1 仓库源码解析）

Prisma CLI 使用指南服务初始化、prisma.yml 配置与 HTTP 代理基于 prisma1 仓库源码解析【免费下载链接】prisma1 Database Tools incl. ORM, Migrations and Admin UI (Postgres, MySQL MongoDB) [deprecated]项目地址: https://gitcode.com/gh_mirrors/pr/prisma1Prisma CLI 是管理 Prisma 数据库服务Database-as-a-Service的主要命令行工具负责服务的初始化、数据模型datamodel的部署、种子数据导入导出、订阅配置等全生命周期操作。本篇指南以 Prisma 1.x 官方文档《CLI Command Reference — Overview》为核心骨架结合本仓库gh_mirrors/pr/prisma1中cli/packages下的 TypeScript 源码实现系统讲解 CLI 的安装与初始化流程、prisma.yml服务定义文件的结构与变量机制以及企业内网环境下 CLI 的 HTTP 代理配置帮助读者掌握一套完整可用的 Prisma 服务开发与部署工作流。CLI 在 Prisma 架构中的角色Prisma CLI 是开发者与 Prisma 数据库服务之间的核心交互界面。从 CLI 官方 Overview 文档 的定义来看CLI 承担了 Prisma 服务的所有管理操作而其中最关键的两部分配置都围绕它展开服务定义文件prisma.yml定义服务的 API 端点、数据模型文件、认证密钥、订阅 webhook 与钩子hooks等全部配置。详见 prisma.yml 配置参考。数据模型datamodel基于 GraphQL SDL 编写的类型定义是数据库 schema 的根基通过deploy命令部署到 Prisma 服务。相关说明见 数据建模SDL文档。从源码结构看CLI 由多个 npm 包组成实际运行链路如下cli/packages/prisma-cli/src/index.tsCLI 的入口脚本加载prisma-cli-engine的run()启动命令框架并在启动前校验 Node 版本是否满足package.json中engines.node的约束不满足则直接报错退出。cli/packages/prisma-cli-core命令的具体实现包括init、deploy、introspect、import、export、seed、reset、playground等核心子命令。cli/packages/prisma-yml负责解析prisma.yml与全局配置~/.prisma/config.yml也是 HTTP 代理逻辑getProxyAgent的所在地。本仓库cli目录下各包的完整结构可参考 cli/packages 源码目录。快速开始安装与初始化服务全局安装根据 Overview 文档Prisma CLI 通过 npm 以全局方式安装npm install -g prisma安装完成后在终端直接运行prisma即可看到所有可用命令。本仓库对应的命令全集含参数说明位于 CLI 命令参考目录例如prisma-init 命令参考初始化新服务prisma-deploy 命令参考部署服务变更prisma-playground 命令参考打开 GraphQL Playground 调试 API使用 init 初始化服务初始化一个新服务使用init命令然后跟随交互式提示基于所选模板引导式地完成服务搭建prisma init hello-world执行后会进入交互流程需要回答一系列问题例如选择部署方式Demo Server、本地 Docker 还是远程集群选择数据库类型MySQL / PostgreSQL / MongoDB是否为本地环境生成docker-compose.yml是否自动生成 Prisma Client。从 init 命令源码 可以看到该流程的实际实现命令接受可选位置参数dirName目标目录与-e, --endpoint标志预定义服务端点若指定目录中已存在prisma.yml或datamodel.prisma命令会检测到冲突并终止src/commands/init/init.ts#L47-L68。若提供了--endpoint则跳过交互式向导直接写入最小化的prisma.yml只含endpoint与datamodel两行和一份 datamodel 样板文件MongoDB 场景会自动选用datamodel-mongo.prisma样板src/commands/init/init.ts#L74-L97。交互模式下会调用EndpointDialogcli/packages/prisma-cli-core/src/utils/EndpointDialog.ts收集端点与生成器信息最终落盘生成四类文件src/commands/init/init.ts#L155-L176prisma.yml服务定义文件datamodel.prismaGraphQL SDL 数据模型即数据库的根基docker-compose.yml本地集群时Docker 编排配置.env设置了 management secret 时保存PRISMA_MANAGEMENT_API_SECRET环境变量。初始化完成后命令会打印下一步操作提示如cd hello-world、docker-compose up -d、prisma deploy。若选择了客户端生成器还会自动执行一次prisma generatesrc/commands/init/init.ts#L245-L273。深入理解服务定义文件 prisma.yml一个完整的示例prisma.yml是 Prisma 服务的唯一配置来源。以下完整示例摘自 prisma.yml 配置参考文档覆盖了绝大部分常用配置项# REQUIRED # 服务的数据模型可指向多个文件 datamodel: - database/types.graphql - database/enums.graphql # OPTIONAL # Prisma API 的 HTTP 端点编码了三层信息 # * Prisma 服务器本例为 localhost:4466 # * 服务名本例为 myservice # * Stage本例为 dev # 注意当服务名与 stage 均为 default 时可省略 # 即 http://myserver.com/default/default 可简写为 http://myserver.com endpoint: http://localhost:4466/myservice/dev # OPTIONAL # 用于签发 JSON Web TokenJWT的密钥请求 Prisma 端点时 # 需要在 Authorization 头中携带该 token # 警告若未配置 secretPrisma API 将无认证直接可访问 secret: mysecret123 # OPTIONAL # 部署后钩子先从 .graphqlconfig 配置的端点下载 GraphQL schema # 再触发代码生成流程 hooks: post-deploy: - graphql get-schema --project db - graphql codegen # OPTIONAL # 事件订阅配置订阅查询位于 database/subscriptions/welcomeEmail.graphql # 订阅触发时通过 HTTP 调用指定 webhook 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 # 自定义变量可在文件其他位置通过 ${self:custom.xxx} 引用 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各配置项要点解读datamodel必填可以是一个文件路径也可以是文件路径列表。这是数据库 schema 的来源配合 数据模型SDL文档 使用。endpoint可选同时编码服务器、服务名与 stage 三部分信息是deploy、info、playground等命令连接目标服务的依据。secret可选为 Prisma API 提供 JWT 认证能力。源码侧由prisma-yml包解析后注入请求头若缺失则 API 完全公开生产环境务必配置。hooks.post-deploy可选部署后执行的 shell 命令序列常用于拉取最新 schema 并触发客户端代码生成。subscriptions可选声明式事件订阅触发时回调 webhook URL可携带自定义 headers。seed可选首次部署时导入的种子数据文件也可通过deploy --no-seed跳过见下文 deploy 参数。在 prisma.yml 中使用变量变量机制允许在配置值中动态替换内容特别适合存放密钥与多 stage 开发流程中的差异化配置。变量语法为${}包裹的引用# 引用其他来源的变量 yamlKeyXYZ: ${variableSource} # 参见下方变量来源列表 otherYamlKey: ${variableSource, defaultValue} # 带默认值的写法注意变量只能用于属性值不能用于属性键因此无法用变量动态生成配置项的键名。递归自引用self:可以引用prisma.yml文件内部其他属性的值语法为self:前缀加可选的属性路径若不写路径则取整个 YAML 文件作为值subscriptions: sendWelcomeEmail: query: database/subscriptions/sendWelcomeEmail.graphql webhook: url: https://${self:custom.serverlessEndpoint}/sendWelcomeEmail custom: serverlessEndpoint: example.org该机制对prisma.yml内任意属性均生效并不局限于custom字段。环境变量引用env:引用操作系统环境变量语法为env:前缀加环境变量名。典型用途是把 webhook 的鉴权 token 放到环境变量中避免明文入库subscriptions: sendWelcomeEmail: query: database/subscriptions/sendWelcomeEmail.graphql webhook: url: https://example.org/sendWelcomeEmail headers: Authorization: ${env:MY_ENDPOINT_SECRET}变量解析的实际逻辑由 cli/packages/prisma-yml/src/Variables.ts 实现Environment.ts在加载全局与本地配置时会调用变量填充见 Environment.ts。编辑器自动补全与校验若希望在编写prisma.yml时获得自动补全与静态错误检查可以使用社区维护的 JSON Schemaschemastore 上的prismaschema目前支持 VSCode安装 Red Hat 的 vscode-yaml 插件在 VSCode 用户或工作区设置中加入yaml.schemas: { http://json.schemastore.org/prisma: prisma.yml }在prisma.yml上触发智能提示默认快捷键 CtrlSpace即可看到全部可用字段及其说明写错时编辑器会即时标红。部署数据模型从 prisma.yml 到数据库 schema配置好prisma.yml与 datamodel 之后部署服务变更使用deploy命令prisma deploydeploy 命令源码 展示了它支持的主要参数src/commands/deploy/deploy.ts#L35-L72参数简写说明--force-f接受 schema 变更可能带来的数据丢失--new-n强制进入交互模式选择集群--dry-run-d预演部署不真正执行--no-seed—首次部署时跳过种子数据导入--json-j以 JSON 格式输出--no-migrate—禁用迁移需 Prisma 1.26--env-file-e指定注入环境变量的 .env 文件路径--project-p指定 Prisma 定义文件路径--no-generate—禁用隐式客户端生成--skip-hooks—禁用部署钩子部署时CLI 会读取prisma.yml将 datamodel 与服务器上的 schema 做 diff生成迁移计划涉及破坏性变更时需显式传入--force确认数据损失。部署成功后可通过 prisma-playground 命令参考 打开 GraphQL Playground 立即验证 API。企业内网场景为 CLI 配置 HTTP 代理当开发环境处于公司防火墙之后时CLI 访问远程 Prisma 服务如api.cloud.prisma.sh可能被拦截。Prisma CLI 原生支持自定义 HTTP 代理行为与 npm CLI 的代理处理方式非常相似。通过环境变量启用代理CLI 会读取以下环境变量大小写形式均可环境变量作用与示例值HTTP_PROXY或http_proxyhttp 流量的代理地址例如http://localhost:8080HTTPS_PROXY或https_proxyhttps 流量的代理地址例如https://localhost:8080NO_PROXY或no_proxy对指定 URL 禁用代理支持 glob例如*表示全部直连使用本地代理模块快速验证如果手头没有现成代理可以用 npm 的proxy模块在本地起一个简单代理npm install -g proxy DEBUG* proxy -p 8080 HTTP_PROXYhttp://localhost:8080 HTTPS_PROXYhttps://localhost:8080 prisma deploy第一条命令安装并启动监听 8080 端口的本地代理DEBUG*用于打印详细日志第三条命令在启用代理的环境变量下执行prisma deploy验证代理链路是否打通。代理机制的源码实现代理逻辑实现在 cli/packages/prisma-yml/src/utils/getProxyAgent.ts 中核心流程如下getProxyFromURI(uri)getProxyAgent.ts#L46-L85依据目标 URI 的协议选择变量先处理NO_PROXY值为*时直接返回null全部直连否则按逗号分隔的规则列表逐一匹配主机名与端口命中则绕过代理http:协议取HTTP_PROXY || http_proxyhttps:协议依次取HTTPS_PROXY || https_proxy || HTTP_PROXY || http_proxyhttps 可回退到 http 代理变量。getProxyAgent(url)getProxyAgent.ts#L87-L105根据代理地址的协议实例化http-proxy-agentHttpProxyAgent或https-proxy-agentHttpsProxyAgent供请求发送方使用。该 agent 被实际接入到 CLI 的云端 API 请求中——在 Environment.ts 的 requestCloudApi 方法 里对https://api.cloud.prisma.sh的 GraphQL 请求会传入proxy: getProxyAgent(https://api.cloud.prisma.sh)。这意味着启用代理后prisma login、集群列表拉取、deploy到远端集群等依赖云 API 的操作都会自动走代理同理deploy等命令对具体集群端点的请求也遵循同一套代理解析规则。结语Prisma CLI 是 Prisma 服务开发与运维的一站式入口init负责引导式搭建prisma.yml承载全部服务配置deploy完成数据模型到数据库的落地而代理环境变量则保证了受限网络环境下 CLI 依然可用。理解这些核心命令与配置的底层实现本仓库 cli/packages/prisma-cli-core/src/commands 与 cli/packages/prisma-yml/src 中的源码即为权威参考能够帮助你在实际项目中更高效、更安全地使用 Prisma。其余子命令info、introspect、import、export、seed、reset、login等的详细用法可继续翻阅 CLI 命令参考目录 中对应的命令文档。【免费下载链接】prisma1 Database Tools incl. ORM, Migrations and Admin UI (Postgres, MySQL MongoDB) [deprecated]项目地址: https://gitcode.com/gh_mirrors/pr/prisma1创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考