Home

Custom Postgres Config

Supabase projects come with a Postgres cluster that is pre-configured for optimal performance. The configuration is based on a diverse range of workloads as well as the compute add-ons being used in the project. You can override this configuration to better optimize the Postgres cluster for specific workloads.

note

Custom Postgres Config gives you advanced control over your database. Using it to set values that are inappropriate for your workload or compute add-on could cause severe performance degradation or project instability.

Custom Postgres Config#

While most Postgres parameters can be configured from within SQL, some parameters must either be set using a config file, or require superuser access. Custom Postgres Config allows you to configure such parameters.

From the perspective of Postgres, config overrides will show up in the global configuration file. Role or database specific configuration could override them for some scenarios; please refer to the Postgres docs on each parameter for additional details.

Supported Parameters#

The following parameters are available for overrides:

  1. effective_cache_size
  2. maintenance_work_mem
  3. max_connections
  4. max_parallel_maintenance_workers
  5. max_parallel_workers_per_gather
  6. max_parallel_workers
  7. max_worker_processes
  8. session_replication_role
  9. shared_buffers
  10. statement_timeout
  11. work_mem

Setting config using the CLI#

To get started:

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

The postgres config command of the CLI can be used for setting configuration parameters:


_10
$ supabase --experimental --project-ref <project-ref> postgres-config update --config max_parallel_workers=6 --config shared_buffers=250MB
_10
- Custom Postgres Config -
_10
Config |Value |
_10
shared_buffers |250MB |
_10
max_parallel_workers |6 |
_10
- End of Custom Postgres Config -

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:


_10
$ supabase --experimental --project-ref <project-ref> postgres-config update --config max_parallel_workers=3 --replace-existing-overrides
_10
_10
- Custom Postgres Config -
_10
Config |Value |
_10
max_parallel_workers |3 |
_10
- End of Custom Postgres Config -

Considerations#

  1. The Postgres cluster will be restarted in order to change the configuration being used. This will cause momentary disruption to existing database connections; in most cases this should not take more than a few seconds.
  2. Custom Postgres Config will always override the default optimizations generated by Supabase. When changing compute add-ons, this may require manual updates to any relevant overrides that have been applied.
© Supabase Inc—ContributingAuthor StyleguideOpen SourceSupaSquad