Merge pull request #14963 from supabase/da/config-overrides-page

feat: add docs on custom postgres config

apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts

@@ -995,6 +995,7 @@ export const platform: NavMenuConstant = {
       url: undefined,
       items: [
         { name: 'Access Control', url: '/guides/platform/access-control' },
+        { name: 'Custom Postgres Config', url: '/guides/platform/custom-postgres-config' },
         { name: 'Database Size', url: '/guides/platform/database-size' },
         { name: 'HTTP Status Codes', url: '/guides/platform/http-status-codes' },
         { name: 'Logging', url: '/guides/platform/logs' },

apps/docs/pages/guides/platform/custom-postgres-config.mdx

@@ -0,0 +1,75 @@
+import Layout from '~/layouts/DefaultGuideLayout'
+
+export const meta = {
+  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`
+1. `maintenance_work_mem`
+1. `max_connections`
+1. `max_parallel_maintenance_workers`
+1. `max_parallel_workers_per_gather`
+1. `max_parallel_workers`
+1. `max_worker_processes`
+1. `session_replication_role`
+1. `shared_buffers`
+1. `statement_timeout`
+1. `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/resources/supabase-getting-started/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 -
+```
+
+## 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, this may require manual updates to any relevant overrides that have been applied.
+
+export const Page = ({ children }) => <Layout meta={meta} children={children} />
+
+export default Page