Merge pull request #9030 from supabase/da/disk-usage

apps/reference/docs/guides/platform/disk-usage.mdx

@@ -0,0 +1,26 @@
+---
+id: disk-usage
+title: Disk space usage
+description: Learn how database disk space usage is reported.
+---
+
+
+Database disk space usage refers to the _monthly average disk usage_, as reported by Postgres. This metric is reported in your project's [billing page](https://app.supabase.com/project/_/settings/billing) and is updated daily.
+
+For an instantaneous live view of the DB disk space being used by your project, you can execute in Postgres:
+
+```sql
+SELECT SUM(pg_database_size(pg_database.datname)) / (1024 * 1024) as db_size_mb FROM pg_database;
+```
+
+This value is also reported in the [database settings page](https://app.supabase.com/project/_/settings/database).
+
+## Vacuum operations
+
+Postgres does not immediately reclaim the physical space used by dead tuples (i.e., deleted rows) in the DB. Instead, they are internally marked as removed until a [vacuum operation](https://www.postgresql.org/docs/current/routine-vacuuming.html) is executed. As a result, deleting data from your DB may not immediately reduce the reported disk usage.
+
+:::note
+Vacuum operations can temporarily increase resource utilization, which can adversely impact the observed performance of your project until the maintenance is completed.
+:::
+
+Supabase projects have automatic vacuuming, which ensures that these operations are performed regularly to keep the database healthy and performant. However, it can be necessary to either [fine-tune](https://www.percona.com/blog/2018/08/10/tuning-autovacuum-in-postgresql-and-autovacuum-internals/) [the autovacuum parameters](https://www.enterprisedb.com/blog/postgresql-vacuum-and-analyze-best-practice-tips), or [manually initiate](https://www.postgresql.org/docs/current/sql-vacuum.html) vacuum operations. For example, running a manual vacuum after deleting large amounts of data from your DB could help reduce the reported disk usage by Postgres.

apps/reference/docs/guides/platform/performance.mdx

@@ -38,7 +38,7 @@ In such a scenario, you can consider:
 
 ### Configuring clients to use fewer connections
 
-You can use the [pg_stat_activity](https://www.postgresql.org/docs/current/monitoring-stats.html#MONITORING-PG-STAT-ACTIVITY-VIEW) view to debug which clients are holding open connections on your DB.
+You can use the [pg_stat_activity](https://www.postgresql.org/docs/current/monitoring-stats.html#MONITORING-PG-STAT-ACTIVITY-VIEW) view to debug which clients are holding open connections on your DB. `pg_stat_activity` only exposes information on direct connections to the database. Information on the number of connections to pgbouncer is available [via the metrics endpoint](../platform/metrics).
 
 Depending on the clients involved, you might be able to configure them to work with fewer connections (e.g. by imposing a limit on the maximum number of connections they're allowed to use), or shift specific workloads to connect via [pgbouncer](/docs/guides/database/connecting-to-postgres#connection-pool) instead. Transient workflows, which can quickly scale up and down in response to traffic (e.g. serverless functions), can especially benefit from using a connection pooler rather than connecting to the DB directly.
 

apps/reference/nav/_referenceSidebars.js

@@ -189,11 +189,12 @@ const sidebars = {
       label: 'Platform',
       collapsed: true,
       items: [
+        'guides/platform/disk-usage',
         'guides/platform/logs',
         'guides/platform/metrics',
-        'going-into-prod',
         'guides/platform/performance',
         'guides/platform/permissions',
+        'going-into-prod',
       ],
     },
     {