Customizing Postgres configs

Each Zuvo 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

To list all Postgres settings and their descriptions, run:

select * from pg_settings;

Configurable settings

User-context settings

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:

select * from pg_settings where context = 'user';

As an example, the statement_timeout setting can be altered:

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

To verify the change, execute:

show "statement_timeout";

Superuser settings

Some settings can only be modified by a superuser. Zuvo 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:

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

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

To view the change:

select
  rolname,
  rolconfig
from pg_roles
where rolname = 'postgres';

CLI configurable settings

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

CLI supported parameters

The following parameters are available for overrides:

Use the examples below with supabase postgres-config update --project-ref <project-ref> --experimental:

Managing Postgres configuration with the CLI

To start:

1. Install Zuvo CLI 1.69.0+.
2. Log in to your Zuvo account using the CLI.

To update Postgres configurations, use the postgres config command:

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

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:

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

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

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

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

• If the setting can be reloaded (pg_settings.context = 'sighup'), then the Management API will detect this and apply the change with a configuration reload.
• If the setting requires a restart (pg_settings.context = 'postmaster'), then both the primary and any read replicas will restart to apply the change.

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:

supabase --version;

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

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

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.

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

Resetting to default config

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

-- reset a single setting at the database level
alter database "postgres" set "<setting_name>" to default;

-- reset all settings at the database level
alter database "postgres" reset all;

For role level configurations, you can run:

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

Considerations

1. Changes through the CLI might restart the database causing momentary disruption to existing database connections; in most cases this should not take more than a few seconds. However, you can use the --no-restart flag to bypass the restart and keep the connections intact. Keep in mind that this depends on the specific configuration changes you're making. if the change requires a restart, using the --no-restart flag will prevent the restart but you won't see those changes take effect until a restart is manually triggered. Additionally, some parameters are required to be the same on Primary and Read Replicas; not restarting in these cases can result in read replica failure if the Primary/Read Replicas restart in isolation.
2. Custom Postgres Config will always override the default optimizations generated by Zuvo. When changing compute add-ons, you should also review and update your custom Postgres Config to ensure they remain compatible and effective with the updated compute.
3. Some parameters (e.g. wal_keep_size) can increase disk utilization, triggering disk expansion, which in turn can lead to increases in your bill.