Skip to main content
Card class: Hero • Category: Executive Overview

​
At a glance

The percentage of the project’s provisioned disk that is currently consumed. This is the most consequential capacity metric on Supabase because the disk has a tier-bound cap, and hitting that cap does not gracefully degrade: it puts the project into a read-only / restricted mode where writes start failing. For a storefront that means orders cannot be placed, sessions cannot be written and the app effectively stops accepting business, even though the database is otherwise perfectly healthy. The alert fires at 90% precisely because the last 10% can fill faster than you expect (WAL, temp files and autovacuum bloat all eat into it), and recovering from a full disk is far slower than preventing it.
What it tracksThe share of the project’s provisioned disk that is in use, expressed as a percentage.
Data sourcedetail: Supabase tiers cap disk, hitting the cap puts the project in read-only / restricted mode. Read by the Vortex IQ Supabase connector from the project’s disk metrics (database size plus WAL, temp and system overhead) against the provisioned disk size.
Calculation basisdisk_used / disk_provisioned * 100, where disk_used includes the database itself, the write-ahead log, temporary files and system overhead, not just table data.
Time windowRT: a live snapshot, because disk fills continuously and the headroom now is what matters.
Alert trigger> 90%. Above 90% the project is close enough to the cap that the final 10% can be consumed quickly and unexpectedly.
Chart typeGauge (0 to 100%), green below 75%, amber 75 to 90%, red above 90%.
Rolesowner, engineering, operations (DBA / platform / SRE)

​
Calculation

The card divides used disk by provisioned disk and multiplies by 100. The subtlety, and the reason it can surprise teams, is what counts as “used”. The figure is not just the size of your tables. It includes:
  • Table and index data: the obvious component, what pg_database_size() reports.
  • The write-ahead log (WAL): every change is written to WAL first. A long-running transaction, a stalled replication slot, or a burst of writes can grow WAL substantially and temporarily.
  • Temporary files: queries that sort or hash more data than work_mem allows spill to disk. A single large ORDER BY or GROUP BY over a big table can briefly consume gigabytes of temp space.
  • Bloat: dead tuples left behind by updates and deletes until autovacuum reclaims them. High write churn can outpace vacuum and inflate on-disk size well beyond the live row count.
disk_usage_pct = (table_data + indexes + wal + temp_files + bloat + system) 
                 / provisioned_disk * 100
On Supabase the provisioned disk scales with the compute / disk configuration of the tier. The important behaviour is at the ceiling: when the disk fills, Postgres can no longer write, and Supabase places the project into a restricted, read-only-leaning state. Reads may continue, but writes (and therefore orders, sessions, anything that mutates data) fail. This is why the metric is a Hero on the Executive Overview rather than a quiet capacity gauge: a full disk is an outage, not a slowdown. Because temp files and WAL are transient, a disk reading can spike and recover within a single query’s lifetime. The danger is when the baseline (table data plus bloat) has crept up so far that a normal temp-file spike now tips the total over the cap.

​
Worked example

A platform team runs a Supabase project with an 8 GB provisioned disk behind a growing storefront. The reading on 16 Apr 26 at 21:50 BST is 91% (red), up from a steady 78% a week earlier. The alert has fired. Breaking the 7.3 GB of used disk down:
ComponentSizeNote
Table + index data5.1 GBthe legitimate live data set
Bloat (dead tuples)1.4 GBa high-churn sessions table autovacuum is not keeping up with
WAL0.5 GBnormal
Temp files0.2 GBa nightly report spilling to disk
System overhead0.1 GBfixed
The week-on-week jump from 78% to 91% is not real data growth; it is bloat. The sessions table takes heavy update traffic, autovacuum’s default settings cannot reclaim dead tuples fast enough, and 1.4 GB of the disk is now reclaimable space pretending to be data. 
What the platform lead does, in order of urgency:
  1. Immediate headroom: VACUUM (or VACUUM FULL on the sessions table off-peak)
     to reclaim the 1.4 GB of bloat. Brings usage from 91% back to ~74%.
       - Note: VACUUM FULL takes an exclusive lock; run it in a quiet window.
  2. Stop the recurrence: tune autovacuum on the high-churn table
     (lower autovacuum_vacuum_scale_factor) so dead tuples are reclaimed sooner.
  3. Structural: if live data is genuinely on track to fill 8 GB,
     increase the provisioned disk size before it becomes urgent.
Three takeaways a platform team should remember:
  1. Hitting the cap is an outage, not a slowdown. Unlike CPU or memory pressure, which degrades gracefully, a full disk stops writes dead and puts the project in restricted mode. Orders fail. Treat the 90% alert as a deadline, not a suggestion.
  2. Used disk is not the same as data size. A jump in the percentage is often bloat or transient WAL / temp, not real growth. Always break the number down before deciding whether to vacuum (free) or resize the disk (paid and slower). Resizing to fix what was actually bloat just delays the same problem.
  3. The last 10% fills fastest. A single large report spilling temp files, or a stalled replication slot pinning WAL, can consume the final gigabytes in minutes. That is why the alert is at 90% and not 98%: you need the runway to act before the cap.

​
Sibling cards

CardWhy pair it with Database Disk UsageWhat the combination tells you
Supabase Health ScoreDisk is a durability component of the composite.A falling score driven by disk is an imminent-outage warning, not a load issue.
Last Backup Age (hours)If disk fills and writes fail, recovery may lean on backups.High disk plus stale backup is the worst-case durability pairing; fix both.
Database Queries per Second (live)Write-heavy load drives WAL and bloat.A disk climb at a write-QPS spike points at WAL / churn rather than steady data growth.
Slow-Query Rate %Queries that spill to temp files consume disk.A disk spike co-occurring with slow queries points at a large sort or hash spilling to disk.
Memory Usage %When memory is tight, more queries spill to disk temp files.High memory usage plus rising temp-file disk usage are the same root cause: work_mem too small for the workload.
Project UptimeThe cap turns into a write outage.Disk at the cap with uptime still “up” but writes failing is the read-only / restricted state in action.

​
Reconciling against the source

Where to confirm this in Supabase’s own tooling:
Supabase Studio → Reports → Database charts disk usage against the provisioned size and is the closest native equivalent of this gauge. Project Settings → Database shows the provisioned disk size and offers the disk-size increase control. SQL Editor / psql confirms the data component: 
SELECT pg_size_pretty(pg_database_size(current_database())) AS db_size;
and bloat / temp can be inspected with pg_stat_user_tables (dead tuple counts) and pg_stat_database.temp_bytes.
Why our number may legitimately differ from pg_database_size():
ReasonDirectionWhy
Scope of “used”Vortex IQ higherpg_database_size() reports table and index data only. The card includes WAL, temp files and system overhead, which the bare query omits, so the gauge reads higher than the database-size query.
Bloat counted as usedBoth include itDead tuples occupy real disk until vacuumed, so both the native size and the gauge count them; vacuuming reduces both.
Transient spikesEither directionWAL and temp files move continuously; a reading taken seconds apart from a manual query can differ if a large query was spilling to disk.
Provisioned vs allocatedPossible mismatchThe denominator is the provisioned disk for the tier; confirm it in Project Settings if the percentage looks off.
Cross-connector reconciliation:
CardExpected relationshipWhat causes divergence
supabase.supabase-health-scoreDisk above 90% should drag the composite into amber/red.A green score with high disk means the disk threshold was relaxed in Sensitivity; revisit it before the cap.
supabase.database-queries-per-second-liveA write-QPS surge precedes WAL-driven disk climbs.Disk climbing at flat write QPS points at bloat or a stalled replication slot, not load.

​
Known limitations / FAQs

What actually happens when the disk hits the cap? The project enters a restricted, read-only-leaning state. Postgres cannot write, so any statement that mutates data (inserts, updates, deletes, and therefore orders, new sessions, anything transactional) fails, while reads may continue. For a storefront this is an effective outage even though the database process is still running. Recovery means freeing space (vacuum) or increasing the provisioned disk, both of which take time, which is why the 90% alert exists to give you runway. My table data is only 5 GB but the gauge says 91% of 8 GB. Where did the rest go? Used disk includes more than table data: the write-ahead log, temporary files from queries that spill to disk, system overhead and, most often, bloat (dead tuples from updates and deletes that autovacuum has not yet reclaimed). Break the figure down before acting; a jump is frequently reclaimable bloat rather than real growth, and a VACUUM will return the space for free. Should I just increase the disk size when this alerts? Only after you have ruled out bloat and transient spikes. Resizing the disk is the right fix for genuine data growth, but if the climb was actually 1.4 GB of dead tuples, a VACUUM is free and instant whereas a resize costs money and only delays the same problem. Diagnose first: vacuum for bloat, tune autovacuum for recurring churn, resize for real growth. Can disk usage go down on its own? Partly. Transient components (WAL, temp files) shrink automatically once the transaction or query that created them finishes, and autovacuum reclaims bloat over time. But the live data baseline only ever grows unless you delete data, and deleted rows do not free space until vacuumed. So a gauge that ratchets steadily upward is real growth; one that spikes and recovers is transient. Why is the alert at 90% rather than higher? Because the final stretch fills fastest and the consequence is severe. A single large report spilling temp files, a stalled replication slot pinning WAL, or a burst of writes can consume the last gigabytes in minutes, and a full disk is an outage that is slow to recover from. Alerting at 90% gives you the runway to vacuum or resize before the cap. The threshold is configurable per profile in the Sensitivity tab if your baseline genuinely runs hotter. Does a stalled replication slot really affect disk? Yes, and it is a classic silent filler. Postgres cannot recycle WAL segments that a replication slot has not yet acknowledged, so an inactive or stuck slot (a dropped read replica, a paused logical-replication consumer) pins WAL on disk indefinitely. Disk creeps up with no data growth and no obvious cause. Check pg_replication_slots for inactive slots if disk is climbing inexplicably. Free-tier projects have a small disk. Does the metric behave differently? The mechanism is identical; the cap is just lower, so the same temp-file or bloat spike consumes a larger share of the total and tips you over faster. On smaller tiers the headroom between normal usage and the cap is thinner, which makes proactive vacuuming and a watchful eye on this gauge even more important.

​
Tracked live in Vortex IQ Nerve Centre

Database Disk Usage % is one of hundreds of KPI pulses Vortex IQ tracks across Supabase and 70+ other ecommerce connectors. Nerve Centre runs the detection layer; Vortex Mind investigates the cause when something moves; Ask Viq lets you interrogate any number in plain English. Start for free or book a demo to see this metric running on your own data.