直接连接

概述

¥Overview

无论你是通过 Prisma ORM 还是其他 ORM、数据库库/工具连接到 Prisma Postgres，Prisma Postgres 都是你应用的完美选择。如果你将其与 Prisma ORM 一起使用，Prisma Postgres 内置连接池和集成缓存层（由 Prisma 加速 提供支持）。

¥Prisma Postgres is the perfect choice for your applications, whether you connect to it via Prisma ORM or any other ORM, database library / tool of your choice. If you use it with Prisma ORM, Prisma Postgres comes with built-in connection pooling and an integrated caching layer (powered by Prisma Accelerate).

如果你通过其他工具连接到它，你可以使用 直接连接字符串 按照常规 PostgreSQL 格式进行操作。

¥If you connect to it via another tool, you can do so with a direct connection string following the conventional PostgreSQL format.

如何通过直接 TCP 连接到 Prisma Postgres

¥How to connect to Prisma Postgres via direct TCP

为了获取直接连接字符串，你需要：

¥In order to get a direct connection string, you need to:

1. 在你的 账户中打开一个项目（或创建一个新项目）

   ¥Open a project in your account (or create a new one)

2. 导航到具有活动 Prisma Postgres 实例的环境

   ¥Navigate to a environment with an active Prisma Postgres instance

3. 点击项目侧边栏中的“API 密钥”选项卡

   ¥Click the API Keys tab in the project's sidenav

4. 点击“创建 API 密钥”按钮

   ¥Click the Create API key button

5. 在弹出窗口中，输入 API 密钥的名称，然后单击“创建”。

   ¥In the popup, provide a Name for the API key and click Create

6. 复制以 postgres:// 开头的连接字符串，这是你的直接连接字符串。

   ¥Copy the connection string starting with postgres://, this is your direct connection string

连接字符串

¥Connection string

格式

¥Format

通过直接 TCP 连接到 Prisma Postgres 时，你的 连接字符串 如下所示：

¥When you connect to Prisma Postgres via direct TCP, your connection string looks as follows:

DATABASE_URL="postgres://USER:PASSWORD@db.prisma.io:5432/?sslmode=require"

当你在 中为 Prisma Postgres 实例生成凭据时，会提供 USER 和 PASSWORD 值。以下是包含示例值的示例：

¥The USER and PASSWORD values are provided when you generate credentials for your Prisma Postgres instance in the . Here is an example with sample values:

DATABASE_URL="postgres://2f9881cc7eef46f094ac913df34c1fb441502fe66cbe28cc48998d4e6b20336b:sk_QZ3u8fMPFfBzOID4ol-mV@db.prisma.io:5432/?sslmode=require"

SSL 模式

¥SSL mode

通过直接 TCP 连接到 Prisma Postgres 时需要 SSL 模式，因此你需要将 sslmode=require 附加到 TCP 连接字符串中。

¥SSL mode is required when connecting to Prisma Postgres via direct TCP, so you need to append sslmode=require to your TCP connection string.

计费

¥Billing

使用直接 TCP 连接到 Prisma Postgres 实例时，每个 SQL 查询都算作一个 计费操作。了解更多关于我们的 定价页面 的信息。

¥When using direct TCP to connect to a Prisma Postgres instance, every SQL query is counted as a billable operation. Learn more on our pricing page.

临时限制

¥Temporary limitations

关闭空闲连接

¥Closing idle connections

Prisma Postgres 会在长时间空闲后关闭连接。如果你的应用中出现这种情况，你可以重新打开一个新连接。（大多数数据库客户端会自动重新连接。）

¥Prisma Postgres closes idle connections after an extended period of time. If that happens in your application, you can re-open a new connection. (Most database clients re-connect automatically.)

连接限制

¥Connection limit

在早期访问阶段，直接连接适用以下连接限制：

¥While direct connections are in Early Access, the following connection limits apply:

	入门版（免费）	专业版	商业
连接限制	最多 20 条	最多 20 条	最多 20 条

查询和事务超时

¥Query and transaction timeouts

在早期访问阶段，直接连接适用以下超时限制：

¥While direct connections are in Early Access, the following timeouts apply:

	入门版（免费）	专业版	商业
查询超时	最多 10 秒	最多 10 秒	最多 10 秒
交互式事务超时	最多 15 秒	最多 15 秒	最多 15 秒

用户权限受限

¥Limited user permissions

用户权限仅限于读取、写入和架构更改。无法创建单独的数据库、管理用户和角色或执行其他管理操作。

¥User permissions are limited to read, write and schema changes. It is not possible to create separate databases, manage users and roles, or perform other administrative actions.

TCP 隧道

¥TCP tunnel

可以使用 @prisma/ppg-tunnel 包（专为本地数据库工作流设计的身份验证代理）通过 TCP 隧道安全地访问 Prisma Postgres。此软件包通过本地 TCP 服务器与 Prisma Postgres 建立安全连接，在自动处理流量路由和身份验证的同时实现安全访问。

¥Prisma Postgres can be accessed securely via a TCP tunnel using the @prisma/ppg-tunnel package, an authentication proxy designed for local database workflows. This package establishes a secure connection to Prisma Postgres through a local TCP server, enabling secure access while automatically handling traffic routing and authentication.

注意

这是 Prisma Postgres 的 抢先体验 功能。不建议将其用于生产环境，也不适用于应用级访问。

¥This is a Early Access feature of Prisma Postgres. It is not recommended for production use and is not intended for application-level access.

在抢先体验版中，TCP 隧道的使用是免费的。

¥While in Early Access, usage of the TCP tunnel will be free of charge.

先决条件

¥Prerequisites

• 你的计算机上已安装 Node.js

  ¥Node.js installed on your machine

• 一个设置为环境变量（名为 DATABASE_URL）的 Prisma Postgres 数据库连接字符串

  ¥A Prisma Postgres database connection string set as an environment variable called DATABASE_URL

导出环境变量

¥Exporting environment variables

隧道要求你将以下 DATABASE_URL 环境变量设置为 Prisma Postgres 实例的连接 URL。如果你在项目中运行隧道命令，并且 .env 文件已经设置了 DATABASE_URL，则可以跳过此步骤，因为隧道会自动获取它。

¥The tunnel expects you to have the following DATABASE_URL environment variable set to the connection URL of your Prisma Postgres instance. If you are running the tunnel command from your project where an .env file has DATABASE_URL already set, you can skip this step as the tunnel will automatically pick it up.

要在终端会话中临时导出 DATABASE_URL 环境变量：

¥To export the DATABASE_URL environment variable temporarily in a terminal session:

macOS

export DATABASE_URL="prisma+postgres://accelerate.prisma-data.net/?api_key=API_KEY"

Linux

export DATABASE_URL="prisma+postgres://accelerate.prisma-data.net/?api_key=API_KEY"

Windows

set DATABASE_URL="prisma+postgres://accelerate.prisma-data.net/?api_key=API_KEY"

将 API_KEY 占位符替换为 Prisma Postgres 实例的 API 密钥值。

¥Replace the API_KEY placeholder with the API key value of your Prisma Postgres instance.

启动 TCP 隧道

¥Starting the TCP tunnel

要启动代理服务器，请运行以下命令：

¥To start the proxy server, run the following command:

npx @prisma/ppg-tunnel

Show CLI results

Prisma Postgres auth proxy listening on 127.0.0.1:52604 🚀

Your connection is authenticated using your Prisma Postgres API key.
...

==============================
hostname:  127.0.0.1
port:      52604
username:  <anything>
password:  <none>
==============================

这将在随机分配的 TCP 端口上启动隧道。代理会自动处理身份验证，因此任何数据库凭据都可以接受。隧道还会加密流量，这意味着客户端应设置为不需要 SSL。

¥This will start the tunnel on a randomly assigned TCP port. The proxy automatically handles authentication, so any database credentials are accepted. The tunnel also encrypts traffic, meaning clients should be set to not require SSL.

你现在可以使用你最喜欢的 PostgreSQL 客户端（例如 psql 或类似 TablePlus 或 DataGrip 的 GUI）连接到你的 Prisma Postgres 编辑器。为此，你只需提供上面输出中的 host 和 port。TCP 隧道将通过 Prisma Postgres 连接 URL 中的 API 密钥进行身份验证，因此你可以省略 username 和 password 的值。

¥You can now connet to your Prisma Postgres editor using your favorite PostgreSQL client, e.g. psql or a GUI like TablePlus or DataGrip. To do so, you only need to provide the host and port from the output above. The TCP tunnel will handle authentication via the API key in your Prisma Postgres connection URL, so you can omit the values for username and password.

自定义主机和端口

¥Customizing host and port

默认情况下，隧道监听 127.0.0.1 并分配一个随机端口。由于它提供对 Prisma Postgres 数据库的访问，因此它应该仅在受信任的网络中公开。你可以使用 --host 和 --port 标志指定自定义主机和端口：

¥By default, the tunnel listens on 127.0.0.1 and assigns a random port. Since it provides access to your Prisma Postgres database, it should only be exposed within a trusted network. You can specify a custom host and port using the --host and --port flags:

npx @prisma/ppg-tunnel --host 127.0.0.1 --port 5432

下一步

¥Next steps

本地隧道使你可以从第三方数据库编辑器（例如 Postico、DataGrip、TablePlus 和 pgAdmin）访问 Prisma Postgres。在此 section 中了解更多信息。

¥The local tunnel enables you to access Prisma Postgres from 3rd party database editors such as Postico, DataGrip, TablePlus and pgAdmin. Learn more in this section.

安全注意事项

¥Security considerations

使用 TCP 隧道时，请注意以下几点：

¥When using the TCP tunnel, keep the following in mind:

• 隧道不支持模式管理（即 Prisma Migrate 之外的 DDL 查询）。

  ¥The tunnel does not support schema management (i.e., DDL queries outside of Prisma Migrate).

• 隧道不应暴露给不受信任的网络。

  ¥The tunnel should not be exposed to untrusted networks.

• 始终安全存储 API 密钥并避免对其进行硬编码。

  ¥Always store API keys securely and avoid hardcoding them.

• 确保只有必要的用户才能直接访问 Prisma Postgres 数据库。

  ¥Ensure that only necessary users have direct access to the Prisma Postgres database.