数据库

连接到您的数据库

Supabase 提供了多种连接到您的 Postgres 数据库的方法，无论您是在前端、后端工作，还是利用无服务器功能。

如何连接到您的 Postgres 数据库#

您如何连接到数据库取决于您从何处连接

  • 对于前端应用程序，请使用数据 API
  • 对于 Postgres 客户端，请使用连接字符串

快速入门#

Prisma

Drizzle

Postgres.js

pgAdmin

PSQL

DBeaver

Metabase

Beekeeper Studio

数据 API 和客户端库#

数据 API 允许您使用 REST 或 GraphQL 请求与数据库进行交互。只要您启用了RLS，您就可以使用这些 API 从前端获取和插入数据。

为了方便起见，您还可以使用Supabase 客户端库，它们以开发人员友好的界面封装了数据 API，并自动处理身份验证。

直接连接#

直接连接字符串直接连接到您的 Postgres 实例。它非常适用于持久性服务器，例如虚拟机 (VM) 和长期运行的容器。示例包括 AWS EC2 机器、Fly.io VM 和 DigitalOcean Droplets。

连接字符串如下所示

1
postgresql://postgres:[YOUR-PASSWORD]@db.abcdefghijklmnopqrst.supabase.co:5432/postgres

通过点击连接，从您的项目仪表板获取项目的直接连接字符串。

连接池#

每个 Supabase 项目都包含一个连接池。当不支持 IPv6 时，这对于持久性服务器是理想的选择。

池化器会话模式#

会话模式连接字符串通过代理连接到您的 Postgres 实例。仅建议在通过 IPv4 网络连接时，作为直接连接的替代方案。

连接字符串如下所示

1
postgres://postgres.apbkobhfnmcqqzqeeqss:[YOUR-PASSWORD]@aws-0-[REGION].pooler.supabase.com:5432/postgres

通过点击连接，从您的项目仪表板获取项目的会话池化器连接字符串。

池化器事务模式#

事务模式连接字符串通过充当连接池的代理连接到您的 Postgres 实例。这对于需要许多瞬时连接的无服务器或边缘功能是理想的选择。

连接字符串如下所示

1
postgres://postgres:[YOUR-PASSWORD]@db.abcdefghijklmnopqrst.supabase.co:6543/postgres

通过点击连接，从您的项目仪表板获取项目的事务池化器连接字符串。

专用池化器#

对于付费客户，我们提供一个与您的 Postgres 数据库共存的专用池化器 (PgBouncer)。这将要求您使用 IPv6 连接，如果这不是一个选项，您可以使用IPv4 附加组件。

专用池化器可确保最佳性能和低延迟，同时占用项目更多的计算资源。如果您的网络支持 IPv6 或您拥有 IPv4 附加组件，我们建议您使用专用池化器而不是共享池化器。

通过点击连接，从您的项目仪表板获取项目的专用池化器连接字符串。

更多关于连接池的信息#

连接池通过重用查询之间的现有连接来提高数据库性能。这减少了建立连接的开销并提高了可伸缩性。

您可以根据后端是持久性还是无服务器，使用应用程序端池化器或服务器端池化器（Supabase 自动提供一个名为 Supavisor 的池化器）。

应用程序端池化器#

应用程序端池化器内置于连接库和 API 服务器中，例如 Prisma、SQLAlchemy 和 PostgREST。它们与 Postgres 或服务器端池化器维护多个活动连接，减少了查询之间建立连接的开销。部署到静态架构（例如长期运行的容器或 VM）时，应用程序端池化器本身就足够了。

服务器端池化器#

Postgres 连接就像 WebSocket。一旦建立，它们就会一直保留，直到客户端（应用程序服务器）断开连接。服务器可能只进行一个 10 毫秒的查询，但却不必要地保留其数据库连接数秒甚至更长时间。

服务器端池化器，例如 Supabase 的Supavisor在事务模式下，位于客户端和数据库之间，可以被视为 Postgres 连接的负载均衡器。

New migration files trigger migrations on the preview instance.
直接连接数据库与使用连接池

它们与数据库保持热连接，并仅在需要时智能地与客户端共享它们，从而最大限度地提高单个连接可以服务的查询量。它们最适合用于管理来自自动伸缩系统（例如边缘和无服务器功能）的查询。

使用 SSL 连接#

您应该尽可能使用 SSL 连接到您的数据库，以防止嗅探和中间人攻击。

您可以从应用程序的仪表板获取连接信息和服务器根证书。

Connection Info and Certificate.

资源#

故障排除和 Postgres 连接字符串常见问题解答#

以下是常见挑战和查询的答案。

什么是“连接拒绝”错误？#

“连接拒绝”错误通常表示您的数据库无法访问。请确保您的 Supabase 项目正在运行，确认您的数据库连接字符串，检查防火墙设置，并验证网络权限。

什么是“致命：密码验证失败”错误？#

当您的凭据不正确时，会发生此错误。请仔细检查 Supabase 仪表板中的用户名和密码。如果问题仍然存在，请从项目设置中重置数据库密码。

如何使用 IPv4 连接？#

Supabase 的默认直接连接仅支持 IPv6。要通过 IPv4 连接，请考虑使用 Supavisor 会话或事务模式，或支持 IPv4 和 IPv6 的连接池（共享或专用）。

Supabase 中的 Postgres 连接字符串在哪里？#

您的连接字符串位于 Supabase 仪表板中。点击页面顶部的连接按钮。

可以同时使用 Supavisor 和 PgBouncer 吗？#

技术上来说，您可以同时使用两者，但除非您明确尝试增加并发客户端连接的总数，否则不建议这样做。在大多数情况下，最好选择 PgBouncer 或 Supavisor 来处理池化或基于事务的流量。直接连接仍然是长时间会话的最佳选择，如果这些会话需要 IPv4，则可以使用 Supavisor 会话模式作为替代方案。同时运行两个连接池会增加在较小的计算层上达到数据库最大连接限制的风险。

默认池大小如何工作？#

Supavisor 和 PgBouncer 独立工作，但都引用相同的池大小设置。例如，如果您将池大小设置为 30，Supavisor 可以向 Postgres 打开最多 30 个服务器端连接。这些连接在会话模式端口 (5432) 和事务模式端口 (6543) 之间共享。每种模式可以独立使用最多 30 个连接，或者在两者之间分配，但两种模式的总连接数不能超过 30。PgBouncer 也可以在相同的限制下打开最多 30 个连接。如果两个池化器都处于活动状态并同时达到其角色/模式限制，您可能会有多达 60 个后端连接访问您的数据库，此外还有任何直接连接。您可以在仪表板的数据库设置中调整池大小。

客户端连接和后端连接有什么区别？#

在使用连接池时，需要了解两个不同的限制。第一个是客户端连接，它指同一时间有多少客户端可以连接到连接池。此数量受您的计算层的“最大连接池客户端”限制限制，并且独立适用于 Supavisor 和 PgBouncer。第二个是后端连接，它是连接池向 Postgres 打开的活动连接数。此数量由该连接池的池大小设置。

1
Total backend load on Postgres =
2
 Direct connections +
3
 Supavisor backend connections (≤ supavisor_pool_size) +
4
 PgBouncer backend connections (≤ pgbouncer_pool_size)
5
≤ Postgres max connections for your compute instance

最大池化器客户端限制是多少？#

您的计算层的“最大池化器客户端”限制分别适用于 Supavisor 和 PgBouncer。一个池化器达到其客户端限制不会影响另一个池化器。当一个池化器达到此限制时，它会停止接受新的客户端连接，直到现有连接关闭，但另一个池化器不受影响。您可以在计算和磁盘限制文档中查看您的层连接限制。

在哪里可以看到当前的连接使用情况？#

您可以从项目仪表板的可观察性部分跟踪连接使用情况。有三个关键报告：

  • 数据库连接：按角色显示活动连接总数（包括直接连接和池化连接）。
  • 专用池化器客户端连接：显示 PgBouncer 的活动客户端连接数。
  • 共享池化器 (Supavisor) 客户端连接：显示 Supavisor 的活动客户端连接数。

请记住，角色页面不是实时的，它显示的是上次刷新时的连接计数。如果您需要精确到秒的数据，请设置 Grafana 或直接在 SQL 编辑器中对 pg_stat_activity 运行查询。我们有一些有用的查询可以检查连接。

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;
1
-- View all connections
2
 SELECT
3
   pg_stat_activity.pid,
4
   ssl AS ssl_connection,
5
   datname AS database,
6
   usename AS connected_role,
7
   application_name,
8
   client_addr,
9
   query,
10
   query_start,
11
   state,
12
   backend_start
13
FROM pg_stat_ssl
14
JOIN pg_stat_activity
15
 ON pg_stat_ssl.pid = pg_stat_activity.pid;

为什么应用程序空闲时有活动连接？#

即使您的应用程序没有进行查询，某些 Supabase 服务也会保持与数据库的持久连接。例如，Storage、PostgREST 和我们的健康检查器都维护长期连接。您通常会看到这些服务的一小部分活动连接基线。

为什么连接字符串有不同的端口？#

不同的模式使用不同的端口

  • 直接连接：5432（数据库服务器）
  • PgBouncer：6543（数据库服务器）
  • Supavisor 事务模式：6543（独立服务器）
  • Supavisor 会话模式：5432（独立服务器）

端口有助于将连接路由到正确的池化器/模式。

连接池是否影响延迟？#

因为专用连接池托管在与您的数据库相同的机器上，所以它比托管在独立服务器上的共享连接池连接延迟更低。直接连接没有连接池开销，但需要 IPv6，除非您拥有 IPv4 附加组件。

如何选择正确的连接方法？#

直接连接

  • 最适合：持久性后端服务
  • 用于迁移、pg_dump、备份和管理工具
  • 限制：默认仅支持 IPv6。IPv4 可作为附加组件提供。

共享连接池

  • 最适合：通用连接（支持 IPv4 和 IPv6）
    • Supavisor 会话模式 → 需要 IPv4 的持久后端
    • Supavisor 事务模式 → 无服务器功能或短期任务
  • 用于应用程序运行时流量（查询、写入）

专用连接池（付费层）

  • 最适合：需要专用资源的高性能应用程序
  • 用于应用程序运行时流量（查询、写入）
  • 使用 PgBouncer

您可以遵循连接方法图中的决策流程，快速为您的环境选择正确的选项。

Decision tree diagram showing when to connect directly to Postgres or use a connection pooler.
在直接 Postgres 连接和连接池之间进行选择