From fe0afd66b8c8d52d228f47db578ebfb68ecbdd6e Mon Sep 17 00:00:00 2001
From: Maksym Ionutsa <123338468+peekknuf@users.noreply.github.com>
Date: Thu, 17 Sep 2026 15:06:23 +0200
Subject: [PATCH] docs(cron): document how to clean up cron.job_run_details
 (#50211)

cron.job_run_details grows unbounded and is never pruned automatically,
even after a job is unscheduled. Add an example that schedules a daily
cleanup job, and link it from the existing disk-usage caution.

## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.

YES

## What kind of change does this PR introduce?

docs update

## What is the current behavior?

No mention of the _necessary_ regular cleanups

## What is the new behavior?

This is now explicitly called out with a weekly clean-up example

<img width="1620" height="654" alt="CleanShot 2026-09-10 at 11 41 25@2x"
src="https://github.com/user-attachments/assets/2f78a051-5994-4f8a-95c2-c96c64679bed"
/>



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

## Summary by CodeRabbit

- **Documentation**
- Updated the cron quickstart guide with guidance on cleaning up job run
history.
- Added an example showing how to schedule a daily cleanup job that
removes records older than seven days.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---
 apps/docs/content/guides/cron/quickstart.mdx | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

diff --git a/apps/docs/content/guides/cron/quickstart.mdx b/apps/docs/content/guides/cron/quickstart.mdx
index 6c6b369c8e3..616aedbb84a 100644
--- a/apps/docs/content/guides/cron/quickstart.mdx
+++ b/apps/docs/content/guides/cron/quickstart.mdx
@@ -210,7 +210,7 @@ limit 10;
 
 <Admonition type="caution">
 
-The records in the `cron.job_run_details` table are not cleaned up automatically. They are also not removed when jobs are unscheduled, which will take up disk space in your database.
+The records in the `cron.job_run_details` table are not cleaned up automatically. They are also not removed when jobs are unscheduled, which will take up disk space in your database. Schedule a cleanup Job to remove old records (see [Clean up job run history](#clean-up-job-run-history) below).
 
 </Admonition>
 
@@ -235,6 +235,22 @@ select cron.schedule (
 );
 ```
 
+### Clean up job run history
+
+{/* <!-- vale off --> */}
+
+`cron.job_run_details` grows with every Job run and is never cleaned up automatically, even after a Job is unscheduled. Schedule a Job to delete old records, keeping only the last 7 days:
+
+{/* <!-- vale on --> */}
+
+```sql
+select cron.schedule(
+  'job-run-details-cleanup', -- name of the cron job
+  '0 0 * * *', -- daily at midnight (GMT)
+  $$ delete from cron.job_run_details where end_time < now() - interval '7 days' $$
+);
+```
+
 ### Run a vacuum every day
 
 {/* <!-- vale off --> */}