自定义 Postgres 配置

每个 Supabase 项目都是一个预配置的 Postgres 集群。你可以覆盖一些配置设置以满足你的需求。这是一个高级话题，除非必要，我们不建议随意更改这些设置。

🌐 Each Supabase project is a pre-configured Postgres cluster. You can override some configuration settings to suit your needs. This is an advanced topic, and we don't recommend touching these settings unless it is necessary.

查看设置 #

🌐 Viewing settings

要列出所有 Postgres 设置及其说明，请运行：

🌐 To list all Postgres settings and their descriptions, run:

1
select * from pg_settings;

可配置设置 #

🌐 Configurable settings

用户上下文设置 #

🌐 User-context settings

pg_settings 表的 context 列说明了更改设置的要求。默认情况下，具有 user 上下文的设置可以在 role 或 database 级别通过 SQL 进行更改。

🌐 The pg_settings table's context column specifies the requirements for changing a setting. By default, those with a user context can be changed at the role or database level with SQL.

要列出所有用户上下文设置，请运行：

🌐 To list all user-context settings, run:

1
select * from pg_settings where context = 'user';

举个例子，可以修改 statement_timeout 设置：

🌐 As an example, the statement_timeout setting can be altered:

1
alter database "postgres" set "statement_timeout" TO '60s';

要验证更改，请执行：

🌐 To verify the change, execute:

1
show "statement_timeout";

超级用户设置 #

🌐 Superuser settings

有些设置只能由超级用户修改。Supabase 预先启用了 supautils 扩展，它允许 postgres 角色保留某些超级用户权限。它可以在 role 级别修改以下保留配置：

🌐 Some settings can only be modified by a superuser. Supabase pre-enables the supautils extension, which allows the postgres role to retain certain superuser privileges. It enables modification of the below reserved configurations at the role level:

例如，要为 postgres 角色启用 log_nested_statements，执行：

🌐 For example, to enable log_nested_statements for the postgres role, execute:

1
alter role "postgres" set "auto_explain.log_nested_statements" to 'on';

查看更改：

🌐 To view the change:

1
select
2
  rolname,
3
  rolconfig
4
from pg_roles
5
where rolname = 'postgres';

CLI 可配置设置 #

🌐 CLI configurable settings

虽然许多 Postgres 参数可以直接配置，但有些配置可以通过 Supabase CLI 在 system 级别进行更改。

🌐 While many Postgres parameters are configurable directly, some configurations can be changed with the Supabase CLI at the system level.

支持的命令行参数 #

🌐 CLI supported parameters

以下参数可以被覆盖：

🌐 The following parameters are available for overrides:

使用下面的例子和 supabase postgres-config update --project-ref <project-ref> --experimental：

使用命令行管理 Postgres 配置 #

🌐 Managing Postgres configuration with the CLI

开始吧：

🌐 To start:

1. 安装 Supabase CLI 1.69.0+。
2. 登录到你的 Supabase 账户，使用 CLI。

要更新 Postgres 配置，请使用 postgres config 命令：

🌐 To update Postgres configurations, use the postgres config command:

1
supabase postgres-config update --config shared_buffers=250MB \
2
--project-ref <project-ref> \
3
--experimental

默认情况下，CLI 会将提供的任何配置覆盖与现有的配置合并。可以使用 --replace-existing-overrides 标志来强制用提供的覆盖完全替换现有的覆盖：

🌐 By default, the CLI will merge any provided config overrides with any existing ones. The --replace-existing-overrides flag can be used to instead force all existing overrides to be replaced with the ones being provided:

1
supabase postgres-config update --config max_parallel_workers=3 \
2
--replace-existing-overrides \
3
--project-ref <project-ref> \
4
--experimental

要删除特定的配置覆盖，使用 postgres-config delete 命令：

🌐 To delete specific configuration overrides, use the postgres-config delete command:

1
supabase postgres-config delete --config shared_buffers,work_mem \
2
--project-ref <project-ref> \
3
--experimental

默认情况下，CLI v2（≥ 2.0.0）会检查参数的上下文并请求正确的操作（重载或重启）:

🌐 By default, CLI v2 (≥ 2.0.0) checks the parameter’s context and requests the correct action (reload or restart):

• 如果这个设置可以重新加载（pg_settings.context = 'sighup'），那么管理 API 会检测到这一点并通过配置重载来应用更改。
• 如果该设置需要重启（pg_settings.context = 'postmaster'），那么主节点和所有只读副本都会重启以应用更改。

要检查某个参数是否可以在不重启的情况下重新加载，请参阅 Postgres 文档。

🌐 To check whether a parameter can be reloaded without a restart, see the Postgres docs.

你可以通过以下检查来确认更改是否已应用：

🌐 You can verify whether changes have been applied with the following checks:

1
supabase --version;

1
-- Check whether the parameters were updated (and if a restart is pending):
2
select name, setting, context, pending_restart
3
from pg_settings
4
where name in ('max_slot_wal_keep_size', 'shared_buffers', 'max_connections');

1
-- If the timestamp hasn’t changed, no restart occurred
2
select pg_postmaster_start_time();

你也可以传入 --no-restart 标志来尝试只重新加载应用。如果参数无法重新加载，变化会保持待处理状态，直到下次重启。

🌐 You can also pass the --no-restart flag to attempt a reload-only apply. If the parameter cannot be reloaded, the change stays pending until the next restart.

1
supabase postgres-config delete --config shared_buffers --no-restart \
2
--project-ref <project-ref> \
3
--experimental

重置为默认配置 #

🌐 Resetting to default config

要在数据库层将设置重置为默认值：

🌐 To reset a setting to its default value at the database level:

1
-- reset a single setting at the database level
2
alter database "postgres" set "<setting_name>" to default;
3
4
-- reset all settings at the database level
5
alter database "postgres" reset all;

对于 role 级别的配置，你可以运行：

🌐 For role level configurations, you can run:

1
alter role "<role_name>" set "<setting_name>" to default;

考虑事项 #

🌐 Considerations

1. 通过 CLI 进行的更改可能会重启数据库，从而暂时中断现有的数据库连接；在大多数情况下，这不会超过几秒钟。不过，你可以使用 --no-restart 标志来跳过重启，保持连接不变。不过要记住，这取决于你正在进行的具体配置更改。如果更改需要重启，使用 --no-restart 标志会阻止重启，但这些更改在手动重启之前不会生效。此外，有些参数要求主库和只读副本保持一致；在这种情况下如果不重启，可能会导致只读副本在主库或只读副本单独重启时出现故障。
2. 自定义 Postgres 配置总是会覆盖 Supabase 生成的默认优化。当更改计算附加组件时，你也应该查看并更新你的自定义 Postgres 配置，以确保它们在更新的计算环境下仍然兼容且有效。
3. 有些参数（例如 wal_keep_size）可能会增加磁盘使用率，从而触发磁盘扩容，这也可能导致账单增加。