dima/supabase
1
0 Fork 0
mirror of https://github.com/supabase/supabase.git synced 2026-10-05 17:35:10 +03:00
Code Issues Packages Projects Releases Wiki Activity

updated pg config docs with new settings (#47939)

Browse Source 
## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.

YES

## What kind of change does this PR introduce?

docs update

## What is the current behavior?

1. Certain
[supautils](https://github.com/supabase/postgres/blob/47d3ff319a0ead8a5a9a2e7dad5950a487834c58/ansible/files/postgresql_config/supautils.conf.j2#L14)
and [CLI
settings](https://github.com/supabase/platform/blob/master/api/apps/mgmt-api/src/routes/v1/projects/ref/config/postgresql.dto.ts)
have not yet been added to the customizing config page.

2. We also list that pg_net settings can be changed at the role level.
That is not the case.

3. We state that certain settings are only configurable via the MGMT
API. They've now been exposed through the CLI

## What is the new behavior?

1. Updated list of exposed settings to include everything referenced in
our supautils and MGMT API config files
2. Removed pg_net references
3. Removed the warning that some settings can only be changed with the
MGMT API

## Additional context


[Linear](https://linear.app/supabase/issue/CE-50/outline-all-grafana-metrics)


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **Documentation**
* Updated the custom Postgres configuration guide to clarify which
settings require superuser privileges.
* Added additional CLI-supported logging and cron configuration options.
* Removed outdated guidance about Management API-only parameters and
restart requirements.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->
This commit is contained in:
TheOtherBrian1 authored and GitHub committed 2026-07-28 12:44:14 -04:00
1 parent fa5eb17277
commit e6623a49ab
1 file changed
+32 -28
Download Patch File Download Diff File Expand all files Collapse all files
apps/docs/content/guides/database/custom-postgres-config.mdx
+32 -28
View File
@@ -48,28 +48,28 @@ show "statement_timeout";
Some settings can only be modified by a superuser. Supabase pre-enables the [`supautils` extension](/blog/roles-postgres-hooks#setting-up-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:
| Setting | Description |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auto_explain.*` | Configures the [auto_explain module](https://www.postgresql.org/docs/current/auto-explain.html). Can be configured to log execution plans for queries expected to exceed x seconds, including function queries. |
| `deadlock_timeout` | Sets the time to wait on a lock before checking for deadlock. |
| `log_lock_waits` | Controls whether a log message is produced when a session waits longer than [deadlock_timeout](https://www.postgresql.org/docs/current/runtime-config-locks.html#GUC-DEADLOCK-TIMEOUT) to acquire a lock. |
| `log_min_duration_statement` | Causes the duration of each completed statement to be logged if the statement ran for at least the specified amount of time. |
| `log_min_messages` | Minimum severity level of messages to log. |
| `log_parameter_max_length` | Sets the maximum length in bytes of data logged for bind parameter values when logging statements. |
| `log_replication_commands` | Logs all replication commands |
| `log_statement` | Controls which SQL statements are logged. Valid values are `none` (off), `ddl`, `mod`, and `all` (all statements). |
| `log_temp_files` | Controls logging of temporary file names and sizes. |
| `pg_net.batch_size` | Sets how many requests the [pg_net extension](/docs/guides/database/extensions/pg_net) can make per second |
| `pg_net.ttl` | Sets how long the [pg_net extension](/docs/guides/database/extensions/pg_net) saves responses |
| `pg_stat_statements.*` | Configures the [pg_stat_statements extension](https://www.postgresql.org/docs/current/pgstatstatements.html). |
| `pgaudit.*` | Configures the [PGAudit extension](/docs/guides/database/extensions/pgaudit). The `log_parameter` is still restricted to protect secrets |
| `pgrst.*` | [`PostgREST` settings](https://docs.postgrest.org/en/stable/references/configuration.html#db-aggregates-enabled) |
| `plan_filter.*` | Configures the [pg_plan_filter extension](/docs/guides/database/extensions/pg_plan_filter) |
| `safeupdate.enabled` | Enables the [safeupdate extension](https://github.com/eradman/pg-safeupdate), which requires a `WHERE` clause on `UPDATE` and `DELETE` statements. |
| `session_replication_role` | Sets the session's behavior for triggers and rewrite rules. |
| `track_functions` | Controls whether function call counts and timing are tracked. Valid values are `none`, `pl` (only procedural-language functions), and `all`. |
| `track_io_timing` | Collects timing statistics for database I/O activity. |
| `wal_compression` | This parameter enables compression of WAL using the specified compression method. |
| Setting | Description |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auto_explain.*` | Configures the [auto_explain module](https://www.postgresql.org/docs/current/auto-explain.html). Can be configured to log execution plans for queries expected to exceed x seconds, including function queries. |
| `deadlock_timeout` | Sets the time to wait on a lock before checking for deadlock. |
| `log_duration` | Logs how long a query ran for, but not the entire query itself. |
| `log_lock_waits` | Controls whether a log message is produced when a session waits longer than [deadlock_timeout](https://www.postgresql.org/docs/current/runtime-config-locks.html#GUC-DEADLOCK-TIMEOUT) to acquire a lock. |
| `log_min_duration_statement` | Logs the duration and text of completed statements whose execution time meets or exceeds the specified threshold |
| `log_min_error_statement` | Determines if the query that induced a log should be recorded as a subfield based on the event's [severity level](https://www.postgresql.org/docs/current/runtime-config-logging.html#RUNTIME-CONFIG-SEVERITY-LEVELS) |
| `log_min_messages` | Minimum severity level of messages to log. |
| `log_parameter_max_length` | Sets the maximum length in bytes of data logged for bind parameter values when logging statements. |
| `log_replication_commands` | Logs all replication commands |
| `log_statement` | Controls which SQL statements are logged. Valid values are `none` (off), `ddl`, `mod`, and `all` (all statements). |
| `log_temp_files` | Controls logging of temporary file names and sizes. |
| `pg_stat_statements.*` | Configures the [pg_stat_statements extension](https://www.postgresql.org/docs/current/pgstatstatements.html). |
| `pgaudit.*` | Configures the [PGAudit extension](/docs/guides/database/extensions/pgaudit). The `log_parameter` is still restricted to protect secrets |
| `pgrst.*` | [`PostgREST` settings](https://docs.postgrest.org/en/stable/references/configuration.html#db-aggregates-enabled) |
| `plan_filter.*` | Configures the [pg_plan_filter extension](/docs/guides/database/extensions/pg_plan_filter) |
| `safeupdate.enabled` | Enables the [safeupdate extension](https://github.com/eradman/pg-safeupdate), which requires a `WHERE` clause on `UPDATE` and `DELETE` statements. |
| `session_replication_role` | Sets the session's behavior for triggers and rewrite rules. |
| `track_functions` | Controls whether function call counts and timing are tracked. Valid values are `none`, `pl` (only procedural-language functions), and `all`. |
| `track_io_timing` | Collects timing statistics for database I/O activity. |
| `wal_compression` | This parameter enables compression of WAL using the specified compression method. |
For example, to enable `log_nested_statements` for the `postgres` role, execute:
@@ -123,10 +123,20 @@ Use the examples below with `supabase postgres-config update --project-ref <proj
| Parameter | Type | Restart | Example |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ------- | ----------------------------------------------- |
| [cron.log_statement](https://github.com/citusdata/pg_cron#extension-settings) | CLI only | Yes | `--config cron.log_statement=false` |
| [checkpoint_timeout](https://www.postgresql.org/docs/current/runtime-config-wal.html#GUC-CHECKPOINT-TIMEOUT) | CLI only | No | `--config checkpoint_timeout=15min` |
| [effective_cache_size](https://www.postgresql.org/docs/current/runtime-config-query.html#GUC-EFFECTIVE-CACHE-SIZE) | CLI + SQL | No | `--config effective_cache_size=8GB` |
| [hot_standby_feedback](https://www.postgresql.org/docs/current/runtime-config-replication.html#GUC-HOT-STANDBY-FEEDBACK) | CLI only | No | `--config hot_standby_feedback=true` |
| [logical_decoding_work_mem](https://www.postgresql.org/docs/current/runtime-config-resource.html#GUC-LOGICAL-DECODING-WORK-MEM) | CLI + SQL | No | `--config logical_decoding_work_mem=128MB` |
| [log_autovacuum_min_duration](https://www.postgresql.org/docs/current/runtime-config-logging.html#GUC-LOG-AUTOVACUUM-MIN-DURATION) | CLI only | No | `--config log_autovacuum_min_duration=10s` |
| [log_checkpoints](https://www.postgresql.org/docs/current/runtime-config-logging.html#GUC-LOG-CHECKPOINTS) | CLI only | No | `--config log_checkpoints=true` |
| [log_connections](https://www.postgresql.org/docs/current/runtime-config-logging.html#GUC-LOG-CONNECTIONS) | CLI only | No | `--config log_connections=true` |
| [log_disconnections](https://www.postgresql.org/docs/current/runtime-config-logging.html#GUC-LOG-DISCONNECTIONS) | CLI only | No | `--config log_disconnections=true` |
| [log_lock_waits](https://www.postgresql.org/docs/current/runtime-config-logging.html#GUC-LOG-LOCK-WAITS) | CLI + SQL | No | `--config log_lock_waits=true` |
| [log_recovery_conflict_waits](https://www.postgresql.org/docs/current/runtime-config-logging.html#GUC-LOG-RECOVERY-CONFLICT-WAITS) | CLI only | No | `--config log_recovery_conflict_waits=true` |
| [log_replication_commands](https://www.postgresql.org/docs/current/runtime-config-logging.html#GUC-LOG-REPLICATION-COMMANDS) | CLI + SQL | No | `--config log_replication_commands=true` |
| [log_startup_progress_interval](https://www.postgresql.org/docs/current/runtime-config-logging.html#GUC-LOG-STARTUP-PROGRESS-INTERVAL) | CLI only | No | `--config log_startup_progress_interval=10s` |
| [log_temp_files](https://www.postgresql.org/docs/current/runtime-config-logging.html#GUC-LOG-TEMP-FILES) | CLI + SQL | No | `--config log_temp_files=10MB` |
| [maintenance_work_mem](https://www.postgresql.org/docs/current/runtime-config-resource.html#GUC-MAINTENANCE-WORK-MEM) | CLI + SQL | No | `--config maintenance_work_mem=512MB` |
| [max_connections](https://www.postgresql.org/docs/current/runtime-config-connection.html#GUC-MAX-CONNECTIONS) (Be aware of [these considerations](/docs/guides/troubleshooting/how-to-change-max-database-connections-_BQ8P5)) | CLI only | Yes | `--config max_connections=200` |
| [max_locks_per_transaction](https://www.postgresql.org/docs/current/runtime-config-locks.html#GUC-MAX-LOCKS-PER-TRANSACTION) | CLI only | Yes | `--config max_locks_per_transaction=128` |
@@ -151,12 +161,6 @@ Use the examples below with `supabase postgres-config update --project-ref <proj
| [wal_sender_timeout](https://www.postgresql.org/docs/current/runtime-config-replication.html#GUC-WAL-SENDER-TIMEOUT) | CLI only | No | `--config wal_sender_timeout=60s` |
| [work_mem](https://www.postgresql.org/docs/current/runtime-config-resource.html#GUC-WORK-MEM) | CLI + SQL | No | `--config work_mem=64MB` |
#### Management API only parameters
Some Postgres settings are configurable through the [Management API](/docs/reference/api/v1-update-postgres-config) but not the CLI. These include logging settings such as `log_connections`. See [Postgres connection logging](/docs/guides/platform/postgres-connection-logging) for details.
`cron.log_statement` (which logs each [pg_cron](/docs/guides/database/extensions/pg_cron) job statement before it runs) is also Management API only. It is a `postmaster`-context parameter, so updating it **requires a database restart** to take effect.
#### Managing Postgres configuration with the CLI
To start: