使用 Prisma Postgres 进行本地开发
Prisma Postgres 是生产级、云原生的数据库，非常适合暂存和生产环境。为了快速迭代和独立测试，您可以通过 prisma dev 命令运行一个本地 Prisma Postgres 实例（由 PGlite 提供支持）。本页解释了如何安装和启动本地 Prisma Postgres 数据库。
本地 Prisma Postgres 处于预览阶段，正在积极开发中。
为 Prisma Postgres 设置本地开发环境
请按照以下步骤为开发设置本地 Prisma Postgres。
本地 Prisma Postgres 需要 Node.js v20 或更高版本
1. 启动本地 Prisma Postgres
进入您的项目并使用以下命令启动本地 Prisma Postgres 服务器
npx prisma dev
这将启动一个本地 Prisma Postgres 服务器，您可以使用 Prisma ORM 或其他工具连接到它。命令的输出如下所示
$ npx prisma dev
✔ Great Success! 😉👍
Your prisma dev server default is ready and listening on ports 63567-63569.
╭──────────────────────────────╮
│[q]uit [h]ttp url [t]cp urls│
╰──────────────────────────────╯
现在按
- q 退出
- h 查看启用通过 Prisma ORM 连接的连接 URL
- t 查看启用通过 任何工具 连接的连接 URL
如果您想通过 Prisma ORM 连接，请按键盘上的 h，复制 DATABASE_URL 并将其存储在您的 .env 文件中。这将用于连接到本地 Prisma Postgres 服务器
DATABASE_URL="prisma+postgres://:51213/?api_key=__API_KEY__"
在开发应用程序时，请保持本地 Prisma Postgres 服务器在后台运行。
2. 应用迁移和填充数据
然后在另一个终端选项卡中，运行 prisma migrate dev 命令来创建数据库并运行迁移
npx prisma migrate dev
在运行 prisma migrate dev 命令之前，请确保本地 Prisma Postgres 服务器正在运行。
如果您必须使用不同的端口，请附加--port <number>（例如，npx prisma migrate dev --port 5422）并更新您的 DATABASE_URL（或其他连接设置）以匹配。
这将创建数据库并运行迁移。
如果您有填充脚本来填充数据库，您也应该在此步骤中运行它。
3. 在本地运行您的应用程序
启动您应用程序的开发服务器。您现在可以使用 Prisma ORM 对本地 Prisma Postgres 实例执行查询。
要过渡到生产环境，您只需在 .env 文件中更新数据库 URL，将其替换为 Prisma Postgres 连接 URL，而无需额外的应用程序逻辑更改。
使用不同的本地 Prisma Postgres 实例
您可以通过 prisma dev 命令的 --name (-n) 选项定位特定的本地 Prisma Postgres 实例，例如
npx prisma dev --name mydb1
每当您将 --name mydb1 传递给 prisma dev 时，该命令将返回指向名为 mydb1 的本地实例的相同连接字符串。
停止 Prisma Postgres 实例
您可以使用此命令停止正在运行的 Prisma Postgres 实例
npx prisma dev stop <glob>
<glob> 是一个全局模式的占位符，用于指定应停止哪些本地 Prisma Postgres 实例，例如
npx prisma dev stop mydb # stops a DB called `mydb`
要停止所有以 mydb 开头的数据库（例如 mydb-dev 和 mydb-prod），您可以使用全局模式
npx prisma dev stop mydb* # stops all DBs starting with `mydb`
删除 Prisma Postgres 实例
Prisma Postgres 将本地 Prisma Postgres 实例的信息和数据保存在文件系统上。要删除不再使用的数据库的任何痕迹，您可以运行以下命令
npx prisma dev rm <glob>
<glob> 是一个全局模式的占位符，用于指定应删除哪些本地 Prisma Postgres 实例，例如
npx prisma dev rm mydb # removes a DB called `mydb`
要停止所有以 mydb 开头的数据库（例如 mydb-dev 和 mydb-prod），您可以使用全局模式
npx prisma dev rm mydb* # removes all DBs starting with `mydb`
将本地 Prisma Postgres 与任何 ORM 一起使用
本地 Prisma Postgres 支持直接 TCP 连接，允许您通过任何工具连接到它。
为了连接到您的本地 Prisma Postgres 实例，请使用 prisma dev 返回的 postgres:// 连接字符串。
通过 Prisma VS Code 扩展管理本地 Prisma Postgres 实例
Prisma VS Code 扩展 具有专门的 UI 用于管理 Prisma Postgres 实例。
要使用它，请安装 VS Code 扩展并在 VS Code 编辑器的活动栏中找到 Prisma 标志。它支持以下工作流
- 创建和删除数据库
- 启动和停止特定数据库的服务器
- “推送到云端”：将数据库从本地移动到远程
以编程方式管理本地 Prisma Postgres
您无需调用 CLI 即可从 Node.js 启动和停止本地 Prisma Postgres 服务器。这使用了 @prisma/dev 中未记录、不稳定的 API，并且可能会在不另行通知的情况下更改。请自行承担风险使用。它对于每个测试或套件都需要一个临时本地数据库的集成测试特别有用。
这是一个完整的可运行示例，运行时将打印 [{abba: 1}]
import { Client } from 'pg'
import { unstable_startServer } from '@prisma/dev'
import { getPort } from 'get-port-please'
async function startLocalPrisma(name: string) {
const port = await getPort()
return await unstable_startServer({
name, // required, use a unique name if running tests in parallel
port, //optional, defaults to 51213
databasePort: port + 1, // optional, defaults to 51214
shadowDatabasePort: port + 2, // optional, defaults to 51215
persistenceMode: 'stateless' // optional, defaults to 'stateless'. Use 'stateful' to persist data between runs
})
}
// Usage in tests
const server = await startLocalPrisma(`my-tests-${Date.now()}`)
try {
const client = new Client({ connectionString: server.database.connectionString })
await client.connect()
const res = await client.query(`SELECT 1 as "abba"`)
console.log(res.rows)
client.end()
} finally {
await server.close!()
}
API 参数
unstable_startServer() 函数接受以下选项
| 参数 | 必需 | 描述 | 默认值 |
|---|---|---|---|
名称 | ✅ | 本地 Prisma Postgres 实例的唯一标识符。并行运行多个服务器时使用不同的名称。 | — |
port | ❌ | Prisma 引擎服务器的端口。如果端口已被占用，则抛出错误。 | 51213 |
databasePort | ❌ | 嵌入式 PostgreSQL 数据库的端口。用于所有 Prisma ORM 连接。 | 51214 |
shadowDatabasePort | ❌ | 迁移期间使用的影子数据库端口。 | 51215 |
persistenceMode | ❌ | 定义数据如何持久化 • 'stateless' — 两次运行之间不保留任何数据• 'stateful' — 数据在本地持久化 | 'stateless' |
您可以使用 get-port-please 等库动态选择可用端口，以避免在运行多个实例时发生冲突。
备注
- 并发运行测试时，请分配唯一的端口和
name值。 - 使用
server.database.connectionString连接 Postgres 客户端或 ORM。 - 此模式非常适合运行需要本地数据库的测试。
已知限制
缓存是本地模拟的
Prisma Postgres 缓存 在本地进行模拟。查询始终直接与本地 Prisma Postgres 实例交互，绕过缓存配置
const users = await prisma.user.findMany({
cache: { ttl: 60 },
});
当您在暂存和生产环境中使用 Prisma Postgres 时，缓存正常工作。
仅限单连接
本地 Prisma Postgres 数据库服务器一次只接受一个连接。额外的连接尝试将排队，直到活动连接关闭。此限制足以满足大多数本地开发和测试场景。
不支持 HTTPS 连接
本地 Prisma Postgres 服务器不使用 HTTPS。我们不建议自行托管它。