From 85dd04b0df92ca3bcd34aea80f1737a397332d92 Mon Sep 17 00:00:00 2001
From: Nedunchezhiyan-M <131742855+Nedunchezhiyan-M@users.noreply.github.com>
Date: Mon, 13 Apr 2026 19:59:09 +0530
Subject: [PATCH] fix(docs): clarify Free Plan 500 MB limit is database size,
 not disk size (#44457)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary

- The Free Plan section in `database-size.mdx` was ambiguous — it said
"when you exceed the 500 MB limit" without specifying which limit
- Clarified that the 500 MB threshold is the **database size** limit
(actual Postgres data), while Free Plan projects include 1 GB of total
disk space
- This explains why read-only mode triggers before total disk usage is
reached

Closes #43487

## Test plan

- [ ] Documentation renders correctly at
`/docs/guides/platform/database-size`
- [ ] Wording is unambiguous about database size vs disk size
distinction

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

* **Documentation**
* Clarified Free Plan read-only mode: the 500 MB threshold applies to
database size (Postgres data), not overall disk usage.
* Made Pro Plan instructions explicit: upgrading increases the database
size quota rather than a generic disk limit.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---
 apps/docs/content/guides/platform/database-size.mdx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/apps/docs/content/guides/platform/database-size.mdx b/apps/docs/content/guides/platform/database-size.mdx
index 0a62ab9a75a..30f38d8121d 100644
--- a/apps/docs/content/guides/platform/database-size.mdx
+++ b/apps/docs/content/guides/platform/database-size.mdx
@@ -109,9 +109,9 @@ Due to restrictions on the underlying cloud provider, disk modifications are lim
 
 ### Free Plan behavior
 
-Free Plan projects enter [read-only](#read-only-mode) mode when you exceed the 500 MB limit. Once in read-only mode, you have these options:
+Free Plan projects enter [read-only](#read-only-mode) mode when your **database size** exceeds 500 MB. Note that this is the _database size_ limit (the size of your actual Postgres data), not the _disk size_. Free Plan projects include 1 GB of disk space, but read-only mode is triggered by the 500 MB database size quota. Once in read-only mode, you have these options:
 
-- [Upgrade to the Pro Plan](/dashboard/org/_/billing) to increase the limit to 8 GB. [Disable the Spend Cap](https://app.supabase.com/org/_/billing?panel=costControl) if you want your Pro instance to auto-scale beyond the 8 GB disk size limit.
+- [Upgrade to the Pro Plan](/dashboard/org/_/billing) to increase the database size quota. [Disable the Spend Cap](https://app.supabase.com/org/_/billing?panel=costControl) if you want your Pro instance to auto-scale beyond the 8 GB disk size limit.
 - [Disable read-only mode](#disabling-read-only-mode) and reduce your database size.
 
 ### Read-only mode