Skip to main content

Prisma Postgres 的本地开发

Prisma Postgres 是生产级云原生数据库，非常适合暂存和生产环境。为了快速迭代和独立测试，你可以通过 prisma dev 命令运行本地 Prisma Postgres 实例（由 PGlite 提供支持）。本页介绍如何安装和启动本地 Prisma Postgres 数据库。

¥Prisma Postgres is a production-grade, cloud-native database and is ideal for staging and production environments. For rapid iteration and isolated testing, you can run a local Prisma Postgres instance (powered by PGlite) via the prisma dev command. This page explains how to install and launch a local Prisma Postgres database.

注意

本地 Prisma Postgres 位于 预览 中，并且正在积极开发中。

¥Local Prisma Postgres is in Preview and is being actively developed.

为 Prisma Postgres 设置本地开发​

¥Setting up local development for Prisma Postgres

按照以下步骤设置本地 Prisma Postgres 以进行开发。

¥Follow these steps to set up local Prisma Postgres for development.

注意

请确保你运行的是 Node.js 20 或更高版本，因为本地 Prisma Postgres 需要该版本。

¥Please ensure you're running Node.js 20 or later, as it's required for local Prisma Postgres.

1. 启动本地 Prisma Postgres​

¥ Launching local Prisma Postgres

进入你的项目并使用以下命令启动本地 Prisma Postgres 服务器：

¥Navigate into your project and start the local Prisma Postgres server using the following command:

npx prisma dev

这将启动一个本地 Prisma Postgres 服务器，你可以使用 Prisma ORM 或其他工具连接到该服务器。该命令的输出如下所示：

¥This starts a local Prisma Postgres server that you can connect to using Prisma ORM or another tool. The output of the command looks like this:

$ 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│
╰──────────────────────────────╯

现在点击：

¥Now hit:

  • q 退出

    ¥q to quit

  • h 用于查看通过 Prisma ORM 启用连接的连接 URL

    ¥h to view the connection URL enabling connections via Prisma ORM

  • t 用于查看通过任何工具启用连接的连接 URL

    ¥t to view the connection URL enabling connections via any tool

如果你想通过 Prisma ORM 连接，请在键盘上按下 h，复制 DATABASE_URL 并将其存储在 .env 文件中。这将用于连接到本地 Prisma Postgres 服务器：

¥If you want to connect via Prisma ORM, hit h on your keyboard, copy the DATABASE_URL and store it in your .env file. This will be used to connect to the local Prisma Postgres server:

.env
DATABASE_URL="prisma+postgres://localhost:51213/?api_key=__API_KEY__"

DATABASE_URL 是 Prisma 用于连接到本地 Prisma Postgres 服务器的连接字符串，并且与 Prisma Postgres 扩展 兼容：

¥The DATABASE_URL is a connection string that Prisma uses to connect to the local Prisma Postgres server and is compatible with the Prisma Postgres extension:

import { withAccelerate } from '@prisma/extension-accelerate'

const prisma = new PrismaClient().$extends(withAccelerate())

这可确保在生产环境中从本地 Prisma Postgres 切换到 Prisma Postgres 时无需进行额外的代码更改。

¥This ensures no additional code changes are needed when switching from local Prisma Postgres to Prisma Postgres in production.

在开发应用时，请保持本地 Prisma Postgres 服务器在后台运行。

¥Keep the local Prisma Postgres server running in the background while you work on your application.

2. 应用迁移和播种数据​

¥ Applying migrations and seeding data

然后在单独的终端选项卡中，运行 prisma migrate dev 命令创建数据库并运行迁移：

¥Then in a separate terminal tab, run the prisma migrate dev command to create the database and run the migrations:

npx prisma migrate dev
注意

在运行 prisma migrate dev 命令之前，请确保本地 Prisma Postgres 服务器正在运行。

¥Make sure the local Prisma Postgres server is running before running the prisma migrate dev command.

如果必须使用其他端口，请附加 --port <number>（例如 npx prisma migrate dev --port 5422），并更新你的 DATABASE_URL（或其他连接设置）以匹配。

¥If you must use a different port, append --port <number> (for example, npx prisma migrate dev --port 5422) and update your DATABASE_URL (or other connection settings) to match.

这将创建数据库并运行迁移。

¥This will create the database and run the migrations.

如果你有用于为数据库播种的种子脚本，也应该在此步骤中运行该脚本。

¥If you have a seeder script to seed the database, you should also run it in this step.

3. 在本地运行应用​

¥ Running your application locally

启动应用的开发服务器。现在，你可以使用 Prisma ORM 对本地 Prisma Postgres 实例执行查询。

¥Start your application's development server. You can now perform queries against the local Prisma Postgres instance using Prisma ORM.

要过渡到生产环境，你只需将 .env 文件中的数据库 URL 更新为 Prisma Postgres 连接 URL，无需进行其他应用逻辑更改。

¥To transition to production, you only need to update the database URL in the .env file with a Prisma Postgres connection url without additional application logic changes.

使用不同的本地 Prisma Postgres 实例​

¥Using different local Prisma Postgres instances

你可以通过 prisma dev 命令的 --name (-n) 选项定位到特定的本地 Prisma Postgres 实例，例如：

¥You can target a specific, local Prisma Postgres instance via the --name (-n) option of the prisma dev command, for example:

npx prisma dev --name mydb1

每当你将 --name mydb1 传递给 prisma dev 时，该命令都会返回指向名为 mydb1 的本地实例的相同连接字符串。

¥Whenever you pass the --name mydb1 to prisma dev, the command will return the same connection string pointing to a local instance called mydb1.

将本地 Prisma Postgres 与任何 ORM 结合使用​

¥Use local Prisma Postgres with any ORM

本地 Prisma Postgres 支持 直接 TCP 连接，允许你通过任何工具连接到它。

¥Local Prisma Postgres supports direct TCP connections, allowing you to connect to it via any tool.

要连接到本地 Prisma Postgres 实例，请使用 prisma dev 返回的 postgres:// 连接字符串。

¥In order to connect to your local Prisma Postgres instance, use the postgres:// connection string that's returned by prisma dev.

通过 Prisma VS Code 扩展管理本地 Prisma Postgres 实例​

¥Manage local Prisma Postgres instances via the Prisma VS Code extension

Prisma VS Code 扩展 拥有专用的 UI 来管理 Prisma Postgres 实例。

¥The Prisma VS Code extension has a dedicated UI managing Prisma Postgres instances.

要使用它，请安装 VS Code 扩展，并在 VS Code 编辑器的活动栏中找到 Prisma 徽标。它支持以下工作流程：

¥To use it, install the VS Code extension and find the Prisma logo in the activity bar of your VS Code editor. It enables the following workflows:

  • 创建和删除数据库

    ¥creating and deleting databases

  • 启动和停止特定数据库的服务器

    ¥starting and stopping the server for a particular database

  • "推送到云端"：将数据库从本地移动到远程

    ¥"push to cloud": move a database from local to remote

已知限制​

¥Known limitations

本地缓存已模拟​

¥Caching is mocked locally

Prisma Postgres 缓存 在本地模拟。查询始终直接与本地 Prisma Postgres 实例交互，绕过缓存配置：

¥Prisma Postgres caching is simulated locally. Queries always directly interact with the local Prisma Postgres instance, bypassing cache configurations:

const users = await prisma.user.findMany({
  cache: { ttl: 60 },
});

在预发布和生产环境中使用 Prisma Postgres 时，缓存功能正常工作。

¥Caching works normally when you're using Prisma Postgres in staging and production.

仅限单连接​

¥Single connection only

本地 Prisma Postgres 数据库服务器每次只接受一个连接。额外的连接尝试会排队等待，直到活动连接关闭。此约束对于大多数本地开发和测试场景来说已经足够。

¥The local Prisma Postgres database server accepts one connection at a time. Additional connection attempts queue until the active connection closes. This constraint is sufficient for most local development and testing scenarios.

Prisma Postgres 限制适用于本地 Prisma Postgres 数据库​

¥Prisma Postgres limitations apply to the local Prisma Postgres database

所有 Prisma Postgres 限制也适用于 Prisma 的本地开发 Postgres。有关详细信息，请参阅 Prisma Postgres 限制文档。

¥All Prisma Postgres limitations also apply to local development for Prisma Postgres. Refer to the Prisma Postgres limitations documentation for detailed information.

无 HTTPS 连接​

¥No HTTPS connections

本地 Prisma Postgres 服务器不使用 HTTPS。我们建议不要自行托管。

¥The local Prisma Postgres server doesn't use HTTPS. We advise against self-hosting it.