自定义Postgres配置

每个 Supabase 项目都是一个预配置的 Postgres 集群。您可以根据需要覆盖某些配置设置。这是一个高级主题，除非必要，我们不建议修改这些设置。

自定义 Postgres 配置提供了对数据库的_高级_控制，但不恰当的设置可能导致严重的性能下降或项目不稳定。

查看设置

要列出所有 Postgres 设置及其描述，请运行：

1
select * from pg_settings;

可配置设置

用户上下文设置

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

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

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

例如，可以修改 statement_timeout 设置：

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

要验证更改，请执行：

1
show "statement_timeout";

超级用户设置

部分设置仅能由超级用户修改。Supabase 预先启用了 supautils 扩展，该扩展允许 postgres 角色保留某些超级用户权限。这使得可以在 role 级别修改以下保留配置：

设置项	描述
`auto_explain.log_min_duration`	记录执行时间超过此阈值的查询计划。
`auto_explain.log_nested_statements`	记录嵌套语句的执行计划。
`log_min_messages`	记录消息的最低严重级别。
`pg_net.ttl`	设置 pg_net 扩展保存响应的时间长度
`pg_net.batch_size`	设置 pg_net 扩展每秒可发出的请求数量
`pgaudit.*`	配置 PGAudit 扩展。`log_parameter` 参数仍受限制以保护敏感信息
`pgrst.*`	`PostgREST` 设置
`plan_filter.*`	配置 pg_plan_filter 扩展
`session_replication_role`	设置会话对触发器和重写规则的行为。
`track_io_timing`	收集数据库 I/O 活动的时间统计信息。

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

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

查看变更：

1
2
3
4
5
select  rolname,  rolconfigfrom pg_roleswhere rolname = 'postgres';

CLI 可配置设置

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

通过 CLI 的修改会永久覆盖默认设置，因此 reset all 和 set to default 命令无法恢复原始值。

要覆盖默认设置，您必须在组织中拥有 Owner 或 Administrator 权限。

CLI 支持的参数

如果您需要的设置尚未支持配置，请向我们分享您的使用场景！告诉我们您希望控制哪些设置，我们将在未来更新中考虑添加支持。

以下参数可供覆盖配置：

effective_cache_size（有效缓存大小）
logical_decoding_work_mem（仅限CLI）
maintenance_work_mem（维护工作内存）
max_connections（仅限CLI）
max_locks_per_transaction（仅限CLI）
max_parallel_maintenance_workers（最大并行维护工作线程数）
max_parallel_workers_per_gather（每个Gather节点最大并行工作线程数）
max_parallel_workers（最大并行工作线程数）
max_replication_slots（仅限CLI）
max_slot_wal_keep_size（仅限CLI）
max_standby_archive_delay（仅限CLI）
max_standby_streaming_delay（仅限CLI）
max_wal_size（仅限CLI）
max_wal_senders（仅限CLI）
max_worker_processes（仅限CLI）
session_replication_role（会话复制角色）
shared_buffers（仅限CLI）
statement_timeout（语句超时）
track_activity_query_size（活动查询跟踪大小）
track_commit_timestamp（提交时间戳跟踪）
wal_keep_size（仅限CLI）
wal_sender_timeout（仅限CLI）
work_mem（工作内存）

使用 CLI 管理 Postgres 配置

开始前：

安装 Supabase CLI 1.69.0 或更高版本
使用 CLI 登录您的 Supabase 账户

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

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

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

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

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

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

默认情况下，无论是更新还是删除配置，都会导致数据库及其所有关联的只读副本重启。您可以使用 --no-restart 标志来阻止此行为，尝试在不重启的情况下重新加载更新后的配置。请参考 Postgres 文档以确定特定参数是否可以在不重启的情况下重新加载。

只读副本与自定义配置

Postgres 要求主集群和只读副本之间的多个参数保持同步。

默认情况下，Supabase 会确保正确执行此参数传播。但如果将 --no-restart 行为与那些需要重启才能生效的参数一起使用，用户需要负责确保主节点和只读副本都能及时重启以维持稳定运行状态。在这种情况下，如果配置已更新但未通过重启生效，当主节点或某个只读副本单独重启时（例如由于内存不足事件或硬件故障），可能会导致只读副本故障。

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

重置为默认配置

要将数据库级别的设置重置为默认值：

1
2
3
4
5
-- 重置数据库级别的单个设置alter database "postgres" set "<setting_name>" to default;-- 重置数据库级别的所有设置alter database "postgres" reset all;

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

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

注意事项

通过CLI进行的更改可能会重启数据库，导致现有数据库连接短暂中断；在大多数情况下，中断时间不应超过几秒。但您可以使用--no-restart标志绕过重启以保持连接不受影响。请注意，这取决于您所做的具体配置更改。如果更改需要重启，使用--no-restart标志将阻止重启，但这些更改只有在手动触发重启后才会生效。此外，某些参数在主库和只读副本上必须保持一致；在这些情况下不重启可能导致只读副本在主库/只读副本单独重启时出现故障。
自定义Postgres配置将始终覆盖Supabase生成的默认优化。当更改计算附加组件时，您还应审查并更新自定义Postgres配置，以确保它们与更新后的计算资源保持兼容和有效。
某些参数（例如wal_keep_size）可能会增加磁盘使用率，触发磁盘扩容，进而可能导致账单费用增加。