Skip to main content

Neon

本指南解释了如何：

¥This guide explains how to:

什么是 Neon？​

¥What is Neon?

Neon 是一个完全托管的无服务器 PostgreSQL，具有慷慨的免费套餐。Neon 将存储和计算分开，并提供现代开发者功能，例如无服务器、分支、无底存储等。Neon 是开源的，用 Rust 编写。

¥Neon is a fully managed serverless PostgreSQL with a generous free tier. Neon separates storage and compute, and offers modern developer features such as serverless, branching, bottomless storage, and more. Neon is open source and written in Rust.

了解有关 Neon 此处 的更多信息。

¥Learn more about Neon here.

与其他数据库提供商的共同点​

¥Commonalities with other database providers

将 Prisma ORM 与 Neon 结合使用的许多方面就像将 Prisma ORM 与任何其他 PostgreSQL 数据库结合使用一样。你可以：

¥Many aspects of using Prisma ORM with Neon are just like using Prisma ORM with any other PostgreSQL database. You can:

需要考虑的差异​

¥Differences to consider

Neon 和 PostgreSQL 之间存在一些差异，在决定将 Neon 与 Prisma ORM 结合使用时，你应该注意以下几点：

¥There are a few differences between Neon and PostgreSQL you should be aware of the following when deciding to use Neon with Prisma ORM:

  • Neon 的无服务器模型 — 默认情况下，Neon 在 5 分钟不活动后将 compute 缩放为零。在此状态期间，计算实例处于空闲状态。此功能的一个特点是 "冷启动" 的概念。从空闲状态激活计算需要 500 毫秒到几秒钟的时间。根据连接到数据库所需的时间，你的应用可能会超时。要了解更多信息，请参阅：连接延迟和超时。

    ¥Neon's serverless model — By default, Neon scales a compute to zero after 5 minutes of inactivity. During this state, a compute instance is in idle state. A characteristic of this feature is the concept of a "cold start". Activating a compute from an idle state takes from 500ms to a few seconds. Depending on how long it takes to connect to your database, your application may timeout. To learn more, see: Connection latency and timeouts.

  • Neon 的连接池 — Neon 使用 PgBouncer 提供连接池，支持多达 10,000 个并发连接。要了解更多信息，请参阅：连接池。

    ¥Neon's connection pooler — Neon offers connection pooling using PgBouncer, enabling up to 10,000 concurrent connections. To learn more, see: Connection pooling.

如何使用 Neon 的连接池​

¥How to use Neon's connection pooling

如果你想使用 Neon 中提供的 连接池，则需要在 Prisma 模式的 datasource 块的 url 属性中使用的 DATABASE_URL 环境变量的主机名中添加 -pooler：

¥If you would like to use the connection pooling available in Neon, you will need to add -pooler in the hostname of your DATABASE_URL environment variable used in the url property of the datasource block of your Prisma schema:

.env
# Connect to Neon with Pooling.
DATABASE_URL=postgres://daniel:<password>@ep-mute-rain-952417-pooler.us-east-2.aws.neon.tech:5432/neondb?sslmode=require

如果你想使用 Prisma CLI 对数据库执行其他操作（例如迁移），你将需要添加 DIRECT_URL 环境变量以在 Prisma 模式的 datasource 块的 directUrl 属性中使用，以便 CLI 将 使用直接连接字符串（不带 PgBouncer）：

¥If you would like to use Prisma CLI in order to perform other actions on your database (e.g. for migrations) you will need to add a DIRECT_URL environment variable to use in the directUrl property of the datasource block of your Prisma schema so that the CLI will use a direct connection string (without PgBouncer):

.env
# Connect to Neon with Pooling.
DATABASE_URL=postgres://daniel:<password>@ep-mute-rain-952417-pooler.us-east-2.aws.neon.tech/neondb?sslmode=require

# Direct connection to the database used by Prisma CLI for e.g. migrations.
DIRECT_URL="postgres://daniel:<password>@ep-mute-rain-952417.us-east-2.aws.neon.tech/neondb"

然后，你可以更新 schema.prisma 以使用新的直接 URL：

¥You can then update your schema.prisma to use the new direct URL:

schema.prisma
datasource db {
  provider  = "postgresql"
  url       = env("DATABASE_URL")
  directUrl = env("DIRECT_URL")
}

有关 directUrl 字段的更多信息可以找到 此处。

¥More information about the directUrl field can be found here.

info

我们强烈建议在 DATABASE_URL 环境变量中使用池连接字符串。你将获得 Prisma CLI 的出色开发者体验，同时还允许池化连接，无论部署策略如何。虽然这对于每个应用来说并不是绝对必要的，但无服务器解决方案将不可避免地需要连接池。

¥We strongly recommend using the pooled connection string in your DATABASE_URL environment variable. You will gain the great developer experience of the Prisma CLI while also allowing for connections to be pooled regardless of deployment strategy. While this is not strictly necessary for every app, serverless solutions will inevitably require connection pooling.

解决连接超时问题​

¥Resolving connection timeouts

从 Prisma ORM 连接到 Neon 时发生的连接超时会导致类似于以下内容的错误：

¥A connection timeout that occurs when connecting from Prisma ORM to Neon causes an error similar to the following:

Error: P1001: Can't reach database server at `ep-white-thunder-826300.us-east-2.aws.neon.tech`:`5432`
Please make sure your database server is running at `ep-white-thunder-826300.us-east-2.aws.neon.tech`:`5432`.

此错误很可能意味着 Prisma 客户端创建的连接在 Neon 计算激活之前超时。

¥This error most likely means that the connection created by Prisma Client timed out before the Neon compute was activated.

Neon 计算有两个主要状态：活动和空闲。活动意味着计算当前正在运行。如果 5 分钟内没有查询活动，Neon 默认会将计算置于空闲状态。请参阅 Neon 的 了解更多 文档。

¥A Neon compute has two main states: Active and Idle. Active means that the compute is currently running. If there is no query activity for 5 minutes, Neon places a compute into an idle state by default. Refer to Neon's docs to learn more.

当你从 Prisma ORM 连接到空闲计算时，Neon 会自动激活它。激活通常会在几秒钟内发生，但增加的延迟可能会导致连接超时。要解决此问题，你可以通过添加 connect_timeout 参数来调整 Neon 连接字符串。该参数定义等待打开新连接的最大秒数。默认值为 5 秒。较高的设置应提供避免连接超时问题所需的时间。例如：

¥When you connect to an idle compute from Prisma ORM, Neon automatically activates it. Activation typically happens within a few seconds but added latency can result in a connection timeout. To address this issue, your can adjust your Neon connection string by adding a connect_timeout parameter. This parameter defines the maximum number of seconds to wait for a new connection to be opened. The default value is 5 seconds. A higher setting should provide the time required to avoid connection timeout issues. For example:

DATABASE_URL=postgres://daniel:<password>@ep-mute-rain-952417.us-east-2.aws.neon.tech/neondb?connect_timeout=10
信息

connect_timeout 设置为 0 表示没有超时。

¥A connect_timeout setting of 0 means no timeout.

连接超时的另一个可能原因是 Prisma ORM 的 连接池，它的默认超时为 10 秒。对于 Neon 来说，这通常是足够的时间，但如果你仍然遇到连接超时，你可以尝试通过将 pool_timeout 参数设置为更高的值来增加此限制（除了上述 connect_timeout 设置之外）。例如：

¥Another possible cause of connection timeouts is Prisma ORM's connection pool, which has a default timeout of 10 seconds. This is typically enough time for Neon, but if you are still experiencing connection timeouts, you can try increasing this limit (in addition to the connect_timeout setting described above) by setting the pool_timeout parameter to a higher value. For example:

DATABASE_URL=postgres://daniel:<password>@ep-mute-rain-952417.us-east-2.aws.neon.tech/neondb?connect_timeout=15&pool_timeout=15

如何将 Neon 的无服务器驱动程序与 Prisma ORM 结合使用（预览）​

¥How to use Neon's serverless driver with Prisma ORM (Preview)

Neon 无服务器驱动程序 是适用于 JavaScript 和 TypeScript 的低延迟 Postgres 驱动程序，允许你通过 HTTP 或 WebSockets 代替 TCP 从无服务器和边缘环境查询数据。

¥The Neon serverless driver is a low-latency Postgres driver for JavaScript and TypeScript that allows you to query data from serverless and edge environments over HTTP or WebSockets in place of TCP.

你可以使用 Prisma ORM 以及使用 驱动适配器 的 Neon 无服务器驱动程序。 驱动程序适配器允许你使用与默认 Prisma ORM 提供的不同的数据库驱动程序来与数据库进行通信。

¥You can use Prisma ORM along with the Neon serverless driver using a driver adapter . A driver adapter allows you to use a different database driver from the default Prisma ORM provides to communicate with your database.

信息

此功能在 Prisma ORM 版本 5.4.2 及更高版本的预览版中可用。

¥This feature is available in Preview from Prisma ORM versions 5.4.2 and later.

首先，启用 driverAdapters 预览功能标志：

¥To get started, enable the driverAdapters Preview feature flag:

generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["driverAdapters"]
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

生成 Prisma 客户端：

¥Generate Prisma Client:

npx prisma generate

安装 Neon 的 Prisma ORM 适配器：

¥Install the Prisma ORM adapter for Neon:

npm install @prisma/adapter-neon

更新你的 Prisma 客户端实例：

¥Update your Prisma Client instance:

import { PrismaClient } from '@prisma/client'
import { PrismaNeon } from '@prisma/adapter-neon'
import dotenv from 'dotenv'

dotenv.config()
const connectionString = `${process.env.DATABASE_URL}`

const adapter = new PrismaNeon({ connectionString })
const prisma = new PrismaClient({ adapter })

然后，你可以像平常一样使用 Prisma 客户端，并具有完全的类型安全性。Prisma Migrate、内省和 Prisma Studio 将继续像以前一样工作，使用 Prisma 架构中定义的连接字符串。

¥You can then use Prisma Client as you normally would with full type-safety. Prisma Migrate, introspection, and Prisma Studio will continue working as before, using the connection string defined in the Prisma schema.

注意​

¥Notes

指定 PostgreSQL 模式​

¥Specifying a PostgreSQL schema

你可以在实例化 PrismaNeon 时通过传入 schema 选项来指定 PostgreSQL 模式：

¥You can specify a PostgreSQL schema by passing in the schema option when instantiating PrismaNeon:

const adapter = new PrismaNeon(
  { connectionString },
  { schema: 'myPostgresSchema' })