访问 Postgres

本指南讲解了如何在自托管 Supabase 中连接到 Postgres，可以使用 Supavisor 连接池、可选的 PgBouncer 连接池，或者直接连接。

🌐 This guide explains how to connect to Postgres in self-hosted Supabase, using the Supavisor pooler, the optional PgBouncer pooler, or a direct connection.

自托管的 Supabase 使用 Supavisor 作为默认的连接池。连接池位于 Postgres 之前，并在多个客户端之间共享少量数据库连接，这样可以避免耗尽 Postgres 的连接限制。

🌐 Self-hosted Supabase uses Supavisor as its default connection pooler. A pooler sits in front of Postgres and shares a small set of database connections across many clients, which avoids exhausting Postgres connection limits.

选择一种连接模式 #

🌐 Choose a connection mode

自托管 Supabase 提供三种方式访问 Postgres：

🌐 Self-hosted Supabase offers three ways to reach Postgres:

• 会话模式 - Supavisor 在端口 5432 上运行。适合需要会话级功能的持久客户端，例如 SET 语句、预处理语句、LISTEN/NOTIFY 或咨询锁。每个客户端在会话期间都有专属的 Postgres 连接。默认可用。
• 事务模式 - Supavisor 或 PgBouncer，端口 6543。最适合打开许多短暂连接的无服务器或边缘函数。不支持会话级功能（SET、LISTEN/NOTIFY、跨事务的临时表或咨询锁）。Supavisor 连接池不支持预准备语句；PgBouncer 可以配置支持它们。默认可用。
• 直接连接 - Postgres 绕过连接池器。默认不开放访问 - 详见 暴露 Postgres。最适合迁移、pg_dump 和长时间运行的后端。

通过 Supavisor 连接 #

🌐 Connect through Supavisor [#connect-through-supavisor]

根据堆栈运行的地方，使用你的域名、服务器IP，或者 localhost。

🌐 Use your domain name, your server IP, or localhost, depending on where the stack runs.

对于会话模式连接：

🌐 For session-mode connections:

1
psql 'postgres://postgres.[POOLER_TENANT_ID]:[POSTGRES_PASSWORD]@[your-domain]:5432/postgres'

对于事务模式的连接：

🌐 For transaction-mode connections:

1
psql 'postgres://postgres.[POOLER_TENANT_ID]:[POSTGRES_PASSWORD]@[your-domain]:6543/postgres'

Supavisor 需要“租户 ID”（your-tenant-id）来进行身份验证，而不仅仅是角色。在使用 psql 和命令行参数而不是连接字符串时，-U 参数也必须是 postgres.[POOLER_TENANT_ID]。

🌐 Supavisor requires the "tenant ID" (your-tenant-id) for authentication, not only the role. When using psql with command-line parameters instead of a connection string, the -U parameter must also be postgres.[POOLER_TENANT_ID].

自定义 Supavisor #

🌐 Customize Supavisor

通过你的 .env 文件配置 Supavisor 设置，然后重新创建堆栈以使更改生效：

🌐 Configure Supavisor settings through your .env file, then recreate the stack for changes to take effect:

要查看你当前的 Postgres max_connections 设置：

🌐 To check your current Postgres max_connections setting:

1
docker compose exec db psql -U postgres -c "SHOW max_connections;"

要更改 max_connections 或其他 Postgres 设置，请参阅 自定义 Postgres 配置。

🌐 To change max_connections or other Postgres settings, refer to custom Postgres configuration.

有关 Supavisor 可配置环境变量的完整列表，请查看 docker/CONFIG.md 中的参考列表。

🌐 For the full list of Supavisor's configurable environment variables, check the reference list in docker/CONFIG.md.

使用 PgBouncer 代替 Supavisor #

🌐 Use PgBouncer instead of Supavisor

自托管 Supabase 包含一个可选的 PgBouncer 覆盖。它会禁用 Supavisor，并在 POOLER_PROXY_PORT_TRANSACTION 上以事务模式运行 PgBouncer。

🌐 Self-hosted Supabase includes an optional PgBouncer override. It disables Supavisor and runs PgBouncer in transaction mode on POOLER_PROXY_PORT_TRANSACTION.

用 run.sh 把它加到你的堆栈里：

🌐 Add it to your stack with run.sh:

1
sh run.sh config add pgbouncer
2
sh run.sh start

如果你更喜欢显式地运行 Docker Compose 命令，可以使用 docker compose -f docker-compose.yml -f docker-compose.pgbouncer.yml up -d。

🌐 If you prefer to run Docker Compose commands explicitly, use docker compose -f docker-compose.yml -f docker-compose.pgbouncer.yml up -d.

以 postgres 身份连接：

🌐 To connect as postgres:

1
# tenant ID isn't required for PgBouncer
2
psql 'postgres://postgres:[POSTGRES_PASSWORD]@[your-domain]:6543/postgres'

PgBouncer 的覆盖只提供事务模式。对于会话模式的连接，或者事务模式不支持的功能（例如 SET 语句或 LISTEN/NOTIFY），请通过编辑 docker-compose.pgbouncer.yml 中的环境变量手动重新配置 PgBouncer，或者使用 直接连接。PgBouncer 会重用你在 .env 配置中的 POOLER_DEFAULT_POOL_SIZE 和 POOLER_MAX_CLIENT_CONN 值。

🌐 The PgBouncer override provides transaction mode only. For session-mode connections, or for features that transaction mode does not support (such as SET statements or LISTEN/NOTIFY), reconfigure PgBouncer manually by editing its environment variables in docker-compose.pgbouncer.yml, or use a direct connection. PgBouncer reuses the POOLER_DEFAULT_POOL_SIZE and POOLER_MAX_CLIENT_CONN values from your .env configuration.

暴露 Postgres 以便直接连接 #

🌐 Expose Postgres for direct connections

在默认配置下，Postgres 只能通过连接池访问。要绕过连接池进行迁移、pg_dump 或其他直接连接需求，可以开放 Postgres 端口。

🌐 In the default configuration, Postgres is only reachable through the pooler. To bypass the pooler for migrations, pg_dump, or other direct-connection needs, expose the Postgres port.

如果你使用默认的 Supavisor 堆栈，编辑 docker-compose.yml：

🌐 If you use the default Supavisor stack, edit docker-compose.yml:

1. 通过注释掉或删除整个 supavisor 服务部分来禁用 Supavisor。
2. 通过向 db 服务添加端口映射来暴露 Postgres 端口：

1
db:
2
  ports:
3
    - ${POSTGRES_PORT}:${POSTGRES_PORT}
4
  container_name: supabase-db

如果你使用 PgBouncer 覆盖，Supavisor 已经被禁用。相反，请取消注释 docker-compose.pgbouncer.yml 中的 db 块：

🌐 If you use the PgBouncer override, Supavisor is already disabled. Uncomment the db block in docker-compose.pgbouncer.yml instead:

1
db:
2
  ports:
3
    - ${POSTGRES_PORT}:${POSTGRES_PORT}

重启后，直接使用标准的 Postgres 连接字符串连接：

🌐 After restarting, connect directly with a standard Postgres connection string:

1
postgres://postgres:[POSTGRES_PASSWORD]@[your-server-ip]:5432/[POSTGRES_DB]

额外资源 #

🌐 Additional resources

• Supavisor 文档
• PgBouncer 文档
• 连接到你的数据库