From 8f17fa0e55c6395ddc1515899de128d83931ed55 Mon Sep 17 00:00:00 2001 From: Div Arora Date: Sun, 11 Jun 2023 14:49:52 -0400 Subject: [PATCH 1/2] feat: add docs on custom postgres config --- .../NavigationMenu.constants.ts | 1 + .../platform/custom-postgres-config.mdx | 75 +++++++++++++++++++ 2 files changed, 76 insertions(+) create mode 100644 apps/docs/pages/guides/platform/custom-postgres-config.mdx diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts index e394aa54dfe..34a8091d7df 100644 --- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts +++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts @@ -997,6 +997,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' }, diff --git a/apps/docs/pages/guides/platform/custom-postgres-config.mdx b/apps/docs/pages/guides/platform/custom-postgres-config.mdx new file mode 100644 index 00000000000..1094e82cd40 --- /dev/null +++ b/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 inclue a Postgres cluster that gets configured for optimal performance for a diverse range of workloads, using the compute add-ons being used. Custom configuration overrides can be used in order to better optimize the Postgres cluster for specific workloads that you're using. + + + +Custom Postgres Config allows for advanced control over your database. Using it to set values that are inappropriate for your workload or compute add-on could cause severe performance degredation, or project instability. + + + +## 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 specified using this feature appear to be included 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/) for 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 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 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 of connections to the database; 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 change compute add-ons, this might necessitate manual updates of any relevant overrides that have been applied. + +export const Page = ({ children }) => + +export default Page From f1dfaf953e93726a2e424063196f7d9f06c1aa60 Mon Sep 17 00:00:00 2001 From: Div Arora Date: Mon, 12 Jun 2023 15:42:03 -0400 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Greg Richardson --- .../pages/guides/platform/custom-postgres-config.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/apps/docs/pages/guides/platform/custom-postgres-config.mdx b/apps/docs/pages/guides/platform/custom-postgres-config.mdx index 1094e82cd40..99b1ca987e0 100644 --- a/apps/docs/pages/guides/platform/custom-postgres-config.mdx +++ b/apps/docs/pages/guides/platform/custom-postgres-config.mdx @@ -6,11 +6,11 @@ export const meta = { description: 'Configuring Postgres for your Supabase project.', } -Supabase Projects inclue a Postgres cluster that gets configured for optimal performance for a diverse range of workloads, using the compute add-ons being used. Custom configuration overrides can be used in order to better optimize the Postgres cluster for specific workloads that you're using. +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. -Custom Postgres Config allows for advanced control over your database. Using it to set values that are inappropriate for your workload or compute add-on could cause severe performance degredation, or project instability. +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. @@ -18,7 +18,7 @@ Custom Postgres Config allows for advanced control over your database. Using it 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 specified using this feature appear to be included 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/) for each parameter for additional details. +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 @@ -67,8 +67,8 @@ max_parallel_workers |3 | ## Considerations -1. The Postgres cluster will be restarted in order to change the configuration being used. This will cause momentary disruption of connections to the database; 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 change compute add-ons, this might necessitate manual updates of any relevant overrides that have been applied. +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 }) =>