supabase/apps/docs/content/guides/platform/custom-postgres-config.mdx

---
id: 'custom-postgres-config'
title: 'Custom Postgres Config'
description: 'Configuring Postgres for your Supabase project.'
---

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.

<Admonition type="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.

</Admonition>

## Custom Postgres config

While most Postgres parameters can be configured from [within SQL](https://www.postgresql.org/docs/current/config-setting.html#CONFIG-SETTING-SQL-COMMAND-INTERACTION), 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](https://www.postgresql.org/docs/current/) on each parameter for additional details.

### Supported parameters

The following parameters are available for overrides:

1. [effective_cache_size](https://postgresqlco.nf/doc/en/param/effective_cache_size/)
1. [maintenance_work_mem](https://postgresqlco.nf/doc/en/param/maintenance_work_mem/)
1. [max_connections](https://postgresqlco.nf/doc/en/param/max_connections/)
1. [max_locks_per_transaction](https://postgresqlco.nf/doc/en/param/max_locks_per_transaction/)
1. [max_parallel_maintenance_workers](https://postgresqlco.nf/doc/en/param/max_parallel_maintenance_workers/)
1. [max_parallel_workers_per_gather](https://postgresqlco.nf/doc/en/param/max_parallel_workers_per_gather/)
1. [max_parallel_workers](https://postgresqlco.nf/doc/en/param/max_parallel_workers/)
1. [max_worker_processes](https://postgresqlco.nf/doc/en/param/max_worker_processes/)
1. [session_replication_role](https://postgresqlco.nf/doc/en/param/session_replication_role/)
1. [shared_buffers](https://postgresqlco.nf/doc/en/param/shared_buffers/)
1. [statement_timeout](https://postgresqlco.nf/doc/en/param/statement_timeout/)
1. [work_mem](https://postgresqlco.nf/doc/en/param/work_mem/)

### Setting config using the CLI

To get started:

1. [Install](/docs/guides/resources/supabase-cli) the Supabase CLI 1.69.0+.
1. [Log in](/docs/guides/cli/local-development#log-in-to-the-supabase-cli) to your Supabase account using the CLI.

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

```bash
$ supabase --experimental --project-ref <project-ref> postgres-config update --config max_parallel_workers=6 --config shared_buffers=250MB
- Custom Postgres Config -
Config                  |Value    |
shared_buffers          |250MB    |
max_parallel_workers    |6        |
- 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:

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

- Custom Postgres Config -
Config                  |Value    |
max_parallel_workers    |3        |
- End of Custom Postgres Config -
```

When configuring parameters that require time units, such as `statement_timeout`, the CLI expects a string value with a time unit. Supported units include `ms`, `s`, and `min`.

```bash
$ supabase --experimental --project-ref <project-ref> postgres-config update --config statement_timeout=1000ms

- Custom Postgres Config -
Config            |Value   |
statement_timeout |1000ms  |
- 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.
1. 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.

## Pooler config

You can also [customize some parameters](https://supabase.com/dashboard/project/_/settings/database) for the Connection Pooler:

1. [Pooling Mode](https://supabase.github.io/supavisor/configuration/pool_modes/)
1. [Default Pool Size](https://supabase.github.io/supavisor/configuration/users/)

The default pool size, and the maximum number of clients allowed to connect concurrently is automatically optimized based on the compute add-on being used. At the moment, the Dashboard only reflects any custom configuration being used, and does not include the default optimized numbers used for your project.

Custom Pooler Config may also require manual updates to any relevant overrides when changing compute add-ons.