Customizing Postgres configs

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.

Customizing Postgres configurations provides advanced control over your database, but inappropriate settings can lead to severe performance degradation or project instability.

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. 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:

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 Supabase CLI at the system level.

CLI changes permanently overwrite default settings, so reset all and set to default commands won't revert to the original values.

In order to overwrite the default settings, you must have Owner or Administrator privileges within your organizations.

CLI supported parameters

If a setting you need is not yet configurable, share your use case with us! Let us know what setting you'd like to control, and we'll consider adding support in future updates.

The following parameters are available for overrides:

Parameters marked with Restart: Yes cause the CLI to automatically restart your database (and any read replicas) to apply the change. This may cause a brief interruption to active connections. You can use the --no-restart flag to defer the restart.

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

Managing Postgres configuration with the CLI

To start:

1. Install Supabase CLI 1.69.0+.
2. Log in to your Supabase 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.

Postgres requires several parameters to be synchronized between the Primary cluster and Read Replicas.

By default, Supabase ensures that this propagation is executed correctly. However, if the --no-restart behavior is used in conjunction with parameters that cannot be reloaded without a restart, the user is responsible for ensuring that both the primaries and the read replicas get restarted in a timely manner to ensure a stable running state. Leaving the configuration updated, but not used (via a restart) in such a case can result in read replica failure if the primary, or a read replica, restarts in isolation (e.g. due to an out-of-memory event, or hardware failure).

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 Supabase. 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.