第2章 免费启动：使用 Prisma 在 Postgres 上构建 TypeScript 应用
免费启动基于 Prisma 的 Postgres TypeScript 应用
从空目录开始，在 Prisma Compute 上运行一个带有 Prisma Postgres 数据库的实时 TypeScript 应用，文中列出了免费套餐的配额限制。 使用 Prisma CLI 是构建带有 Postgres 数据库的 TypeScript 应用的最快路径：它能自动搭建应用框架，在本地 Prisma Postgres 数据库上运行（无需账号），并在登录后将应用部署到 Prisma Compute 并在那里创建数据库。所有操作均在免费套餐下进行，无需信用卡。以下步骤演示了手动操作的过程，下方“配合你的 AI 代理使用”中的提示词可端到端自动化完成这一流程。 Prisma Composer 用于声明你的应用：包括服务、数据库及其连接方式。Prisma ORM 为数据提供类型定义。Prisma Postgres 负责数据存储：开发时存储在本地，部署后存储在平台上。一份声明驱动所有环节：同一个 module.ts 既可在本地运行应用，也可将其部署到 Prisma Compute。整个过程预计耗时约 15 分钟。 本教程使用 Hono 模板，让你在每个步骤都能通过 curl 验证一个小型 API。其他模板也适用相同的流程，框架指南中会有详细说明。
前置条件
- Node.js 22.18 或更高版本（若使用 24 系列，需 24.11 或更高；推荐 24），或 Bun - 如果使用 npm，需 npm 11.6.0 或更高版本。Node.js 22 自带 npm 10，因此请先运行 `npm install --global npm@11`；create-prisma 的前置条件中解释了原因 - 部署步骤需要 Prisma Data Platform 账号，创建免费，免费套餐下无需信用卡 - 无需预置数据库：本地运行会自动配置本地 Prisma Postgres，部署时会自动配置线上数据库，两者均基于你的 Composer 声明
已有应用？ 保留现有代码，在旁边添加一个小型 Prisma Composer 声明即可：每个服务端对应一个 service.ts，以及一个 module.ts。服务端从 service.port() 读取端口并绑定 0.0.0.0；“移植现有应用”章节列出了其他必要更改，并提供一个让 AI 代理自动完成的提示词；“引入现有应用”提供了一个完整示例。一旦 `npm run build` 和 `npx prisma dev module.ts` 能正常运行，请从第 5 步继续。SvelteKit 和 Deno 应用目前尚不支持部署到 Prisma Compute。
免费套餐包含什么 本教程中的所有操作均在免费套餐下进行：每月 $0，无需信用卡，无时间限制，无按用量计费。以下是定价页上列出的限制（页面同时也列出了付费套餐）。这些限制适用于你的整个工作区（Workspace），它是 Prisma 账号中承载所有项目和数据库的计费单位，因此每个数值是工作区内所有资源共享的，而非分配给每个数据库。
Prisma ORM 在两款产品中均为可选：Prisma Postgres 可配合任何 PostgreSQL 客户端使用，Compute 也可运行不使用 Prisma ORM 的应用。参见“使用 Compute 是否需要 Prisma ORM？”。本教程的脚手架使用了 Prisma ORM 8，这是一个候选发布版本；参见“发布状态”。
Prisma Postgres | 限制项 | 免费套餐 | | 操作数 | 每月 200,000 次 | | 存储 | 1.01 GB | | 数据库数量 | 50 个 | | 数据传输 | 无限制 | | 连接池连接数 | 10 | | 直接连接数 | 10 | | 自动备份 | 无 |
每个查询计为一次操作，无论读写。参见“什么是操作？”。直接连接是指 pg_dump 等 PostgreSQL 工具建立的连接，其中 10 个中有 5 个保留给平台操作使用；参见“连接限制”。免费套餐无自动备份，且 Prisma Postgres 尚不支持将数据库恢复到历史时间点，因此请通过直接连接使用 pg_dump（PostgreSQL 命令行备份工具）自行保留副本。参见“备份”。
Prisma Compute | 计量项 | 免费套餐 | | 请求数 | 每月 1,000,000 次 | | 预留内存 | 每月 360 GB-小时 | | 活跃 CPU | 每月 4 vCPU-小时 | | 出站带宽 | 每月 10 GB |
GB-小时指分配 1 GB 内存一小时；vCPU-小时指 1 个虚拟 CPU 运行一小时。内存仅在应用运行中或你选择保持其唤醒状态时计算，因为空闲应用会缩放至零：停止运行且不产生费用。出站带宽指应用发送到互联网的数据，入站请求不计入。它与数据库无限制的数据传输是分开的：免费套餐下，Compute 每月包含 10 GB 出站带宽。参见“Compute 定价”了解每个计量项的含义。
检查用量并升级 免费套餐不按用量计费，因此达到限额不会产生额外费用。操作数及 Compute 的四个计量项是月度限额，而存储和数据库数量不与月份绑定。
要查看数据库的用量，运行 `npx prisma postgres usage
若要超越限额，请将工作区升级为付费套餐。付费套餐包含更多的操作数、存储和请求额度，超出部分按用量计费。Compute 的内存、CPU 和带宽在付费套餐中按使用量计费，可设置消费上限。费率详见定价页。
配合你的 AI 代理使用 如果你倾向于将任务交给编码代理，此提示词将运行与入门指南相同的流程，并自动选择 Hono 模板： 该提示词使用 npm 和 Node.js。在 Bun 环境下，请将 `npm create prisma@latest --` 替换为 `bun create prisma@latest`，`npx` 替换为 `bunx`，`npm run` 替换为 `bun run`。
配合你的 AI 代理使用 创建一个由 Prisma Composer 和 Prisma ORM 构建的新 Hono API，在本地运行，并部署到 Prisma Compute。
首先检查版本：`node --version` 必须显示 22.18 或更高（24 系列需 24.11 或更高）。如果使用 npm，`npm --version` 必须显示 11.6.0 或更高；Node.js 22 自带 npm 10，因此若 npm 版本较低，请先在步骤 1 前运行 `npm install --global npm@11`。
1. 搭建框架：`npm create prisma@latest -- my-app --template hono --provider postgres --yes`。然后在 `my-app` 目录下运行 `npx prisma@latest init`，确认脚手架安装的 Prisma 代理技能是最新的，并使用它们。
2. 首先阅读 `module.ts` 和 `service.ts`：Composer 模块负责配置数据库和服务，`dev` 和 `deploy` 命令即基于此操作。
3. 构建并在本地运行：`npm run build`，然后在后台启动 `npx prisma dev module.ts`，等待其打印出本地 URL。这将配置本地 Prisma Postgres 数据库并应用契约；无需 DATABASE_URL。应用首次查询时会自动填充示例用户。使用 curl 验证本地 URL 的 /users 端点返回填充的用户，然后停止 `dev`。
4. 部署：检查 `npx prisma auth whoami`；如果未登录，停止并要求运行 `npx prisma auth login`（会打开浏览器）。脚手架已在 `migrations/app/` 下编写了基线迁移；注意其目录名，以 `_init` 结尾。脚手架的 `prisma.config.ts` 中的 `composer` 部分已设置部署区域，无需添加。然后运行 `npx prisma deploy module.ts`，并使用 curl 验证线上 URL 的 /users 端点。部署会创建项目并根据模块声明配置数据库；无需传递 DATABASE_URL。
5. 演进模式：在 `src/prisma/contract.prisma` 的 User 模型中添加 `role String @default("member")`，运行 `npx prisma contract emit`，在 `src/prisma/users.ts` 的类型化 select 和返回对象中添加 `"role"`，并使用 `npx prisma migration plan --name add-user-role --from
1. 搭建应用 一条命令即可创建带有 Prisma ORM 集成的 Composer 声明应用： bun create prisma@latest my-app --template hono --provider postgres --no-deploy 响应提示中的契约编写风格、包管理器和代理技能，或传递 `--authoring`、`--package-manager` 和 `--skills` 标志以跳过（参见 create-prisma 参考；Deno 项目目前尚不支持部署到 Prisma Compute，因此本教程使用 Node.js 或 Bun）。然后进入项目： cd my-app 如果你使用编码代理，请运行一次 `npx prisma@latest init`。脚手架已运行过该命令，因此在新项目上 init 会确认设置并报告每个步骤已完成：Prisma 包内置的代理技能已同步，package.json 中有一个 postinstall 钩子（`prisma skills sync || exit 0`）在每次安装时重新同步，另有一个 skills:sync 脚本用于手动刷新。再次运行 init 是修复 Prisma 包升级后设置问题的方法。参见“技能”。
2. Composer 应用 从声明开始，因为它是后续所有命令的操作对象。脚手架在两个文件中声明了整个应用，prisma.config.ts 保存部署配置。module.ts 即应用本身：它配置 Prisma Postgres 数据库和服务，并将两者连接起来： module.ts import { module } from "@prisma/composer"; import { postgres } from "@prisma/composer-prisma-cloud/orm";
import { appContract } from "./src/prisma/composer.ts"; import app from "./service.ts";
export default module("my-app", ({ provision }) => { const database = provision( postgres({ name: "database", contract: appContract, config: "./prisma.config.ts", }), { id: "database" }, );
provision(app, { deps: { database } }); }); service.ts 声明服务本身：名称、对数据库的依赖关系，以及构建方式： service.ts import node from "@prisma/composer/node"; import { compute } from "@prisma/composer-prisma-cloud"; import { postgres } from "@prisma/composer-prisma-cloud/orm";
import { appContract } from "./src/prisma/composer.ts";
export default compute({ name: "app", deps: { database: postgres(appContract), }, build: node({ module: import.meta.url, entry: "./dist/server.mjs" }), }); prisma.config.ts 是本项目的 Prisma 配置：Prisma CLI 读取它，但应用代码永远不会导入它。其 orm 部分将 Prisma ORM 指向你的契约和数据库，skills 部分列出了你在提示中选择的代理，deploy 配置即 composer 部分：部署应用的扩展和保存部署状态存储。composer 部分已命名首次部署创建项目所需的区域 us-east-1，因此部署前无需设置。若要部署到其他位置，请在首次部署前在此处更改区域；区域 ID 列表见“限制”。
下方文件展示的是选择使用 Claude Code 编写 Prisma 模式且选择 Claude 作为代理技能的情况。你的 skills 列表保存了你选择的代理，TypeScript 编写将契约指向 contract.ts 并添加输出路径。 prisma.config.ts import { definePrismaConfig } from "prisma/config"; import { defineConfig as ormConfig } from "@prisma/orm-postgres/config"; import { defineConfig as composer } from "@prisma/composer/config"; import { nodeBuild } from "@prisma/composer/node/control"; import { prismaCloud, prismaState } from "@prisma/composer-prisma-cloud/control";
export default definePrismaConfig({ skills: { agents: ["claude"], }, orm: ormConfig({ contract: "./src/prisma/contract.prisma", db: { connection: process.env.DATABASE_URL!, }, }), composer: composer({ extensions: [prismaCloud({ region: "us-east-1" }), nodeBuild()], state: prismaState(), }), }); 注意声明中没有连接字符串。数据库是一个声明的依赖项，由契约提供类型，Composer 会在应用运行的任何位置注入连接。orm 部分中的 DATABASE_URL 仅用于直接连接数据库的 ORM 命令，例如步骤 4 末尾的 db:* 脚本；prisma dev 和 prisma deploy 不需要它。声明是普通的 TypeScript：`npx tsc --noEmit` 可检查连接，错误会在编译而非部署阶段失败。Composer 完整覆盖模型：模块、服务、依赖项和一方构建块。
3. Prisma ORM 数据模型 数据层位于 src/prisma/ 下。你的模式是 src/prisma/contract.prisma 中的初始契约；`npm run contract:emit` 将其编译为查询类型检查所依据的契约工件，src/prisma/db.ts 是路由处理程序导入的类型化客户端。src/index.ts 中的 /users 路由是调用普通 Prisma ORM 查询的普通 Hono 代码。 准备好对自有数据进行建模时，修改契约，重新生成，编译器会引导你处理受影响的每个查询。基础章节涵盖了查询模式。
4. 在本地 Prisma Postgres 上运行 构建服务端，然后在本地启动整个声明： bun run build bunx prisma dev module.ts dev 会配置本地 Prisma Postgres 数据库，应用契约，启动服务，并在一切就绪时打印应用本地 URL。无需账号、凭据或连接字符串；参见“本地开发”了解本地平台如何工作。 应用首次查询数据库时会自动填充示例用户。确认 API 返回填充的行。dev 持续运行直到按下 Ctrl-C，因此在第二个终端中运行 curl。dev 还会选择空闲端口并打印 URL，如果与此处显示的 3000 不同，请使用它打印的 URL： curl http://localhost:3000/users [ { "id": "1", "email": "alice@prisma.io", "username": "alice", "name": "Alice", "createdAt": "2026-08-24 13:51:34.797+00" }, { "id": "2", "email": "bob@prisma.io", "username": "bob", "name": "Bob", "createdAt": "2026-08-24 13:51:34.803+00" }, { "id": "3", "email": "carol@prisma.io", "username": "carol", "name": "Carol", "createdAt": "2026-08-24 13:51:34.804+00" } ] 如果偏好框架自带的开发服务器，`npm run dev` 可直接运行。Composer 不管理该模式，因此应用需要在 DATABASE_URL 中提供你自己的数据库。使用 CLI 创建一个与模块名称不同的项目中的数据库，以免与步骤 5 部署创建的项目冲突： bunx prisma auth login bunx prisma project create my-app-local bunx prisma postgres create mydb `postgres create` 仅打印一次连接字符串；将其导出为 DATABASE_URL，如需更多可用 `npx prisma postgres connection create mydb` 生成。package.json 中的 db:* 脚本用于初始化和验证该数据库。参见 postgres。
5. 将应用和数据库部署到 Prisma Compute
登录一次（会打开浏览器）：
bunx prisma auth login
部署的数据库通过你提交的迁移演进，因此第一个迁移必须创建起始模式。脚手架已将其规划为 migrations/app/
6. 验证线上 URL curl https://xyz.ewr.prisma.build/users 相同的三个用户返回，现在由位于数据库旁边的生产环境提供，由部署应用的首次查询填充。可安全地多次重新部署：再次构建，再次部署，平台仅应用差异。这包括删除操作，因为你的模块是事实来源：从 module.ts 删除一个配置项，再次部署，资源将从平台消失。参见“移除资源”。
7. 演进数据模型 在线应用总会超越初始模式，因此给用户添加角色。在契约中添加一行： src/prisma/contract.prisma // use prisma-8
model User {
id Int @id @default(autoincrement())
email String @unique
username String?
name String?
role String @default("member")
posts Post[]
createdAt TimestamptzString @default(now())
updatedAt temporal.updatedAtString()
}
重新生成契约，然后规划承载此更改的迁移，基于步骤 5 提交的基线迁移链式进行：
bunx prisma contract emit
bunx prisma migration plan --name add-user-role --from
8. 清理（可选）
项目会持续运行，直到你将其移除。删除项目会移除服务和数据库，因此命令要求重复输入项目 ID 以确认（使用 `npx prisma project list` 查找）：
bunx prisma project delete
后续步骤
- 学习 Composer：服务、数据库、存储和定时作业之间的类型化契约。 - 选择你的框架：Next.js、Nuxt、Astro、NestJS、TanStack Start 等的相同流程。 - 分支与预览：每个分支如何获得独立环境。 - 学习基础：读取、写入、关联和事务。 - 推送时部署：连接 GitHub 并添加部署工作流，使每次推送都进行部署，每个分支带有预览环境。
在 GitHub 上编辑 选择 Prisma ORM 配置路径：在新或现有项目中尝试 Prisma ORM 的最快路径。 部署你的第一个应用：从终端到 Prisma Compute 上的实时 URL，使用 Prisma Composer 将 TypeScript 应用从零开始或从现有应用部署。
