连接池和限制

了解如何在连接模式之间进行选择、设置连接池大小，以及弄清楚为什么连接会用完。要连接数据库，请参见 连接到你的数据库。

🌐 Learn how to choose between connection modes, size a pool, and work out why you're running out of connections. To get connected, see Connect to your database.

连接池是如何工作的 #

🌐 How connection pooling works [#how-connection-pooling-works]

连接池通过在查询之间重用现有连接来提升数据库性能。这减少了建立连接的开销，也提高了可扩展性。

🌐 Connection pooling improves database performance by reusing existing connections between queries. This reduces the overhead of establishing connections and improves scalability.

Postgres 连接是一个长期存在的会话。一旦建立，它会一直保持开放，直到客户端断开连接，或者服务器或网络关闭它。服务器可能只执行一次 10 毫秒的查询，但会将数据库连接保持几秒钟甚至更长时间。

🌐 A Postgres connection is a long-lived session. Once established, it stays open until the client disconnects, or until the server or the network closes it. A server might make a single 10 ms query but hold its database connection for seconds or longer.

连接池位于客户端和数据库之间，在多个客户端之间共享一小部分数据库连接，这样当客户端处于空闲状态时，连接就不会被占用。

🌐 A pooler sits between clients and the database and shares a small set of database connections across many clients, so a connection isn't tied up while a client sits idle.

应用端和服务器端的连接池 #

🌐 Application-side and server-side poolers [#application-side-poolers]

有两种，它们会一起工作。

🌐 There are two kinds, and they work together.

应用端连接池 内置在连接库和 API 服务器中，比如 Prisma、SQLAlchemy 和 Postgres.js。它们保持一些连接打开并重复使用。在持久化后端环境中，比如长期运行的容器或虚拟机，单独使用应用端连接池就足够了。

服务器端连接池，比如事务模式下的 Supavisor，会运行在数据库前面，为许多客户端提供服务。当连接来自无服务器或边缘函数，或来自任何水平扩展的环境时，使用它们。这些环境会开启许多短连接，而应用端连接池无法覆盖这种情况。

关于何时需要它们以及如何确定大小的更多信息，请参见 Supavisor 常见问题。

🌐 For more on when each is needed and how to size them, see the Supavisor FAQ.

共享和专用资源池者 #

🌐 Shared and dedicated poolers [#shared-pooler]

Supabase 提供两种连接池器。共享池器 Supavisor 是多租户的，适用于每个项目，并且只支持 IPv4。专用池器 PgBouncer 在付费计划中可用，并与你的 Postgres 实例一起运行。和直接连接一样，它支持 IPv6，如果项目有 IPv4 附加组件，也可以使用 IPv4。

🌐 Supabase offers two poolers. The shared pooler, Supavisor, is multi-tenant, available on every project, and IPv4-only. The dedicated pooler, PgBouncer, is available on paid plans and runs alongside your Postgres instance. Like the direct connection, it is on IPv6, or on IPv4 if the project has the IPv4 add-on.

专用连接池运行在与你的数据库相同的机器上，所以它的连接延迟比运行在独立服务器上的共享连接池更低。它也会使用更多你项目的计算资源。如果你的网络支持 IPv6，或者你有 IPv4 附加组件，推荐使用专用连接池而不是共享连接池。直接连接没有连接池的开销，但除非你有 IPv4 附加组件，否则需要 IPv6。

🌐 The dedicated pooler runs on the same machine as your database, so it connects with lower latency than the shared pooler, which runs on a separate server. It also uses more of your project's compute resources. If your network supports IPv6, or you have the IPv4 add-on, use the dedicated pooler instead of the shared pooler. Direct connections have no pooler overhead, but they require IPv6 unless you have the IPv4 add-on.

在大多数情况下，对于连接池或基于事务的流量，可以选择 PgBouncer 或 Supavisor。对于长时间的会话，直接连接仍然是最佳选择，如果这些会话需要 IPv4，可以使用共享池会话模式。只有在你需要提高客户端并发连接总数时才同时运行两个连接池，并且在较小的计算资源下，可能会更容易达到数据库的最大连接数量限制。

🌐 In most cases, choose either PgBouncer or Supavisor for pooled or transaction-based traffic. Direct connections remain the best choice for long-lived sessions, and shared pooler session mode is the alternative when those sessions need IPv4. Run both poolers at once only when you need to raise the total number of concurrent client connections, and expect a higher risk of hitting your database's maximum connection limit on smaller compute sizes.

连接限制 #

🌐 Connection limits

连接池大小 #

🌐 Pool size [#pooler-pool-size]

连接池大小设置了连接池允许打开多少个到 Postgres 的连接。你可以在 Supabase 控制面板的数据库设置中进行调整。

🌐 Pool size sets how many connections a pooler is allowed to open to Postgres. You can adjust it in Database settings in the Supabase Dashboard.

Supavisor 和 PgBouncer 读取相同的设置，但各自独立应用，所以调高它会同时提高两者的上限。

🌐 Supavisor and PgBouncer read the same setting but apply it independently, so raising it raises the ceiling for both.

至于设置的作用，以及它如何与用户、数据库和连接到你项目的模式组合进行互动，请参阅 Supavisor 常见问题。

🌐 For what the setting counts, and how it interacts with the user, database, and mode combinations connecting to your project, see the Supavisor FAQ.

客户端连接和后端连接 #

🌐 Client connections and backend connections [#client-connections-and-backend-connections]

在使用池化器时，有两个限制需要了解。

🌐 There are two limits to understand when working with poolers.

这两个限制分别独立地适用于 Supavisor 和 PgBouncer。一个连接池达到客户端数量上限不会影响另一个。当一个连接池达到这个上限时，它会停止接受新的客户端连接，直到现有连接关闭。

🌐 Both limits apply independently to Supavisor and PgBouncer. One pooler reaching its client limit doesn't affect the other. When a pooler reaches this limit, it stops accepting new client connections until existing ones close.

1
Direct connections +
2
 Supavisor backend connections +
3
 PgBouncer backend connections
4
< Postgres max connections for your compute instance

保持在最大值以下，而不是正好达到最大值。Supabase 服务会占用自己的连接，包括认证、存储、PostgREST 和健康检查器，这些都算在总量里。管理连接 介绍了应该留多少余量。

🌐 Stay below the maximum rather than at it. Supabase services hold their own connections, including Auth, Storage, PostgREST, and the health checker, and those come out of the same total. Managing connections covers how much headroom to leave.

有关每个计算规模附带的连接数量，请参见 计算和磁盘。有关术语，请参见 Supavisor 和连接术语解释。

🌐 For the connection counts that come with each compute size, see compute and disk. For the terminology, see Supavisor and connection terminology explained.

监控连接使用情况 #

🌐 Monitor connection usage [#monitor-connection-usage]

在 Supabase 仪表板的 可观测性 部分跟踪连接使用情况。有三个报告：

🌐 Track connection usage in the Observability section of the Supabase Dashboard. There are three reports:

• 数据库连接： 按角色统计的总活跃连接数，包括直接连接和连接池连接。
• **专用池客户端连接：**与PgBouncer的活动客户端连接。
• **共享池连接器（Supavisor）客户端连接：**到Supavisor的活跃客户端连接。

这些报告不是实时的。它们显示的是上次刷新时的连接数。要获取即时数据，请在 SQL 编辑器中查询 pg_stat_activity：

🌐 These reports are not real-time. They show the connection count from the last refresh. For up-to-the-second data, query pg_stat_activity in the SQL Editor:

1
-- Count connections by application and user name
2
select
3
  count(usename),
4
  count(application_name),
5
  application_name,
6
  usename
7
from
8
  pg_stat_ssl
9
  join pg_stat_activity on pg_stat_ssl.pid = pg_stat_activity.pid
10
group by usename, application_name;

要列出每个连接及其状态和查询，并查看每个角色属于哪个 Supabase 服务，请参见 管理连接。

🌐 To list every connection with its state and query, and to read which Supabase service each role belongs to, see Managing connections.

相关 #

🌐 Related

• 连接到你的数据库
• 管理连接
• Supavisor 常见问题