企业官网建设流程全解析

• 后端
• 前端
• Web框架
• 开发工具

导读

连接池（Connection Pooling）是 RedwoodJS 应用在生产环境规模化部署时的关键基础设施。在 Serverless 架构下，每个函数实例都会与数据库建立独立的连接，而传统关系型数据库（Postgres 默认 100 个、MySQL 默认 151 个并发连接）很快就会被耗尽。本指南以 RedwoodJS 官方文档《Connection Pooling》为核心，系统讲解连接池的必要性、Prisma Data Proxy / Prisma Accelerate、PgBouncer 的接入方式，以及 Supabase、Heroku、Digital Ocean、AWS 等主流平台的配置细节，并结合仓库源码说明 Redwood CLI 与 Prisma 的封装关系，帮助你为生产级 Redwood 应用正确选型并落地连接池方案。

为什么需要连接池？——Serverless 下的连接危机

数据库的并发连接天花板

关系型数据库对并发客户端连接数有硬性上限，RedwoodJS 官方文档给出了两个最常用的默认值：

• Postgres 默认为 100 个并发连接
• MySQL 默认为 151 个并发连接

传统服务器 vs Serverless 的根本差异

• 传统服务器环境：每个 Web 服务器实例通常只维护一个数据库连接。要耗尽数据库连接数，需要极大的流量和足够多的 Web 服务器实例，因此连接数上限通常不是瓶颈。
• Serverless 环境：每次函数调用都可能启动一个全新实例，每个函数实例都直接与数据库建立连接。当流量高峰到来，成百上千个函数实例并发运行，数据库连接数会被迅速耗尽，直接导致连接错误。

因此，RedwoodJS 文档给出的结论是：生产环境的 Redwood 应用应当启用连接池以正确扩展 Serverless 函数，并建议在数据库前面加一层连接池服务——把它想象成数据库的负载均衡器（load balancer）：连接池持有到数据库的有限连接，代理并排队客户端连接请求，从而平滑消化瞬时并发。

Redwood 与 Prisma：连接配置的入口

RedwoodJS 的数据层基于 Prisma，连接池的所有配置最终都落在 Prisma 的DATABASE_URL环境变量上。理解 Redwood CLI 对 Prisma 的封装，有助于你在配置连接串时知道该用哪条命令。

Redwood CLI 封装 Prisma CLI

仓库中的 packages/cli/src/commands/prisma.js 定义了一个轻量级封装命令：

export const command = 'prisma [commands..]' export const description = 'Run Prisma CLI with experimental features'

该命令的 handler 位于 packages/cli/src/commands/prismaHandler.js，其核心逻辑是：

• 对generate、introspect、db、migrate、studio、format等命令自动注入--schema参数，指向api/db/schema.prisma（通过rwjsPaths.api.dbSchema定位）；
• 将 Redwood 传入的其余命令与选项原样转发给node_modules/.bin/prisma（通过 execa 执行）；
• 支持yarn rw prisma <command> help形式的帮助信息转换。

因此，在 Redwood 应用内，你既可以：

yarn rw prisma migrate dev # Redwood 自动带上 --schema api/db/schema.prisma

也可以直接：

yarn prisma migrate dev # 完全跳过 Redwood CLI 的自动选项，由你手动指定 schema

Prisma Schema 中的连接声明

连接池的所有参数都是通过DATABASE_URL传入的，这一点体现在所有 Redwood 项目的 Prisma schema 中。例如__fixtures__/test-project/api/db/schema.prisma中的标准写法：

datasource db { provider = "sqlite" url = env("DATABASE_URL") } generator client { provider = "prisma-client-js" }

在实际生产环境中，provider通常改为"postgresql"或"mysql"，而url = env("DATABASE_URL")保持不动，连接串本身在.env文件中通过环境变量注入。连接池方案要做的，就是改造这段DATABASE_URL连接串（增加特定 query 参数、切换主机与端口），而无需改动 schema。

值得注意的是，Redwood 的日志模块（packages/api/src/logger/index.ts）会将DATABASE_URL列入需要脱敏/过滤的敏感环境变量，避免在日志中泄露连接凭据，这提醒我们在分享配置时也要注意隐藏连接串中的用户名密码。

Prisma Data Proxy（v5 时代的 Prisma 托管连接池）

RedwoodJS 5.x 文档推荐的第一个方案是Prisma Data Proxy（Prisma 数据平台提供）。它面向使用 Prisma 的 Redwood 应用提供数据库连接管理与连接池能力，支持MySQL 和 Postgres数据库，并可选择U.S. 或 EU区域。

接入步骤：

1. 免费注册 Prisma Data Platform；
2. 在 onboarding 流程中填入你的数据库连接 URL，并选择区域；
3. 平台会为你的应用生成一个连接字符串；
4. 按照 Prisma 官方 Data Proxy 文档完成配置。

注意：官方文档示例使用 npm 安装依赖。如果你在 Redwood 应用内，更推荐使用yarn redwood prisma（即上文所述 Redwood CLI 对 Prisma CLI 的封装）来访问 Prisma CLI，避免绕过 Redwood 自动注入的--schema等参数。

Prisma 与 PgBouncer：经典的连接代理方案

PgBouncer 的工作原理

PgBouncer位于 Prisma Client 与数据库之间：它自身持有到数据库的一个连接池，代理所有进入的客户端连接，从而显著减少数据库在同一时刻需要处理的进程数。当数据库连接被占满时，PgBouncer 将多余连接排队，待连接释放后再交付。

连接串上的pgbouncer=true标志

要从 Serverless 函数中使用 Prisma Client 配合 PgBouncer，只需在 PostgreSQL 连接 URL 上追加?pgbouncer=true：

postgresql://USER:PASSWORD@HOST:PORT/DATABASE?pgbouncer=true

注意端口差异：PgBouncer 的默认端口通常是6543，而 Postgres 默认端口是5432。连接串中的PORT应指向 PgBouncer 的端口。

迁移（Migrate）与 PgBouncer 的冲突

重要警告：Prisma Migrate 使用数据库事务来检查数据库与 migrations 表的当前状态。因此，在任何使用 PgBouncer 做连接池的环境中执行 Prisma Migrate 命令，都可能报错。

规避方法：执行迁移时，必须绕过 PgBouncer、直接连接数据库（即使用直连地址/端口），迁移完成后再切回池化连接。

这也是为什么许多平台的部署脚本会把「迁移直连 + 运行时池化」分成两套DATABASE_URL（例如DATABASE_URL与DIRECT_URL）来管理。

Supabase：内置 PgBouncer 的托管 Postgres

所有新建的 Supabase 项目都自带基于 PgBouncer 的连接池，无需额外搭建。Redwood 官方推荐使用SSL连接 Supabase 的 Postgres 实例，只需在连接串上把sslmode设为require：

// 非池化连接，通常使用端口 5432 postgresql://postgres:mydb.supabase.co:5432/postgres?sslmode=require // 池化连接，通常使用端口 6543 postgresql://postgres:mydb.supabase.co:6543/postgres?sslmode=require&pgbouncer=true

要点归纳：

• 5432：直连 Postgres（无池化）；
• 6543：经 PgBouncer 池化连接（同时追加pgbouncer=true）；
• sslmode=require：强制 TLS 加密传输。

Heroku：Postgres 连接池，暂不支持 MySQL

Heroku 平台请参考其官方文档中的Postgres Connection Pooling指南。需要注意的是：Heroku 不官方支持 MySQL，因此 Heroku 上的 Redwood 应用应使用 Postgres，并通过 Heroku 提供的连接池能力（PGBouncer buildpack 或 Heroku Postgres 的池化连接）来扩展。

Digital Ocean：托管连接池的完整配置

Digital Ocean 为 Postgres 提供托管的连接池（基于 pgbouncer）。Redwood 文档特别强调：要通过连接池运行迁移，必须把连接参数追加到DATABASE_URL上，让 Prisma 知道要使用 pgbouncer（即 Digital Ocean 连接池的一部分）。

常见报错：prepared statement "s0" already exists

如果遗漏了这些参数，你可能看到如下错误：

Error: Migration engine error: db error: ERROR: prepared statement "s0" already exists

正确的 DATABASE_URL 结构

解决方案是使用如下结构：

<YOUR_CONNECTION_POOL_URL>:25061/defaultdb?connection_limit=3&sslmode=require&pgbouncer=true&connect_timeout=10&pool_timeout=30

需要留意的事项

1. 端口选择：Digital Ocean 连接池提供多个端口。直连（无池化）通常在25060端口，经 pgbouncer 的池化连接在25061端口——必须连接 25061。
2. 调整connection_limit：集群按每 1 GB RAM 提供 25 个连接计算配额；其中3 个连接保留给集群维护，其余连接可分配给连接池。
3. 两个必填参数：pgbouncer=true与pool_timeout=30是通过连接池成功部署的必要条件，缺一不可。
4. MySQL 限制：Digital Ocean 的连接池暂不支持 MySQL（Connection Pooling for MySQL is not yet supported）。

AWS：使用 RDS Proxy

AWS 场景推荐使用Amazon RDS Proxy，它同时支持MySQL 和 PostgreSQL。RDS Proxy 位于 Lambda 函数与 RDS 数据库之间，通过复用一个数据库连接池来处理大量函数实例的并发连接。

RDS Proxy 的关键限制

引用 AWS 官方文档：

你的 RDS Proxy 必须与数据库处于同一个 VPC 中，且代理不能被公开访问。

由于这一限制，开箱即用（out-of-the-box）配置下，只有当你把 Lambda 函数部署到同一个 AWS 账户时，才能使用 RDS Proxy。

替代方案

如果无法满足同账户/VPC 约束，可以直接使用 RDS，但这样可能需要更大的实例来处理生产流量与并发连接数——这实际上是放弃了连接池的扩展收益，因此仅在规模可控时才作为备选。

各方案选型对比与实战决策

选型建议（结合仓库与文档证据的推断）：

• 若你的 Redwood 应用已经部署在某个托管平台上，优先使用该平台自带的池化能力（Supabase / Digital Ocean / Heroku / RDS Proxy），配置成本最低；
• 若追求统一的跨平台管理，且数据库规模可控，Prisma Data Proxy（或后续版本的 Prisma Accelerate）是 Prisma 生态的一体化选项；
• 若使用自托管数据库，部署独立的 PgBouncer 是最灵活的方案；
• 无论选择哪种池化方案，Prisma Migrate 迁移时都必须直连数据库，这是文档反复强调的共性约束。

常见问题排查

1. 迁移时报prepared statement "s0" already exists

• 原因：Prisma Client 以pgbouncer=true模式运行，迁移引擎无法在池化连接上可靠管理 prepared statement。
• 解决：迁移时直连数据库（Digital Ocean 用 25060，Supabase 用 5432，PgBouncer 自建则直接指向 Postgres 端口），运行yarn rw prisma migrate dev。

2. Serverless 并发高峰出现too many connections

• 原因：函数实例直连数据库，并发超过 Postgres（100）/ MySQL（151）上限。
• 解决：在数据库前接入连接池，并将连接串切换为池化端口与参数（如pgbouncer=true）。

3. 通过连接池部署失败（Digital Ocean）

• 原因：连接串缺少必要参数。
• 解决：确认连接串同时包含pgbouncer=true与pool_timeout=30，并指向 25061 端口。

4. AWS 上无法使用 RDS Proxy

• 原因：RDS Proxy 与数据库同 VPC 且不可公开访问。
• 解决：将 Lambda 部署到同一 AWS 账户/网络；否则退回直接使用 RDS 并评估实例规格。

结语

连接池是 RedwoodJS Serverless 生产架构中「用最小配置换取最大扩展性」的关键一环。本文从数据库连接上限的本质出发，覆盖了 Redwood 5.x 官方文档推荐的 Prisma Data Proxy、经典 PgBouncer 方案，以及 Supabase、Heroku、Digital Ocean、AWS RDS Proxy 四类主流托管平台的落地细节——从端口选择、连接串参数到迁移时的直连约束。所有配置都围绕同一个核心：让DATABASE_URL正确指向池化层，同时保证迁移命令直连数据库。理解了这一点，你就可以在任何托管平台上为你的 Redwood 应用快速搭建出可扩展的连接池方案。

• 后端
• 前端
• Web框架
• 开发工具