feat: add chat and chat_files cleanup to dbpurge (#23833)

Fixes https://github.com/coder/coder/issues/23910 Adds periodic cleanup of chats and chat files to the dbpurge background goroutine, with a configurable retention period exposed in the Agent settings UI. > 🤖 Written by a Coder Agent. Reviewed by a human.
2026-09-24 15:04:27 +08:00 · 2026-04-08 11:08:09 +01:00
parent 3a612898c6
commit 233343c010
26 changed files with 1514 additions and 4 deletions
@@ -0,0 +1,44 @@
+# Conversation Data Retention
+
+Coder Agents automatically cleans up old conversation data to manage database
+growth. Archived conversations and their associated files are periodically
+purged based on a configurable retention period.
+
+## How it works
+
+A background process runs approximately every 10 minutes to remove expired
+conversation data. Only archived conversations are eligible for deletion —
+active (non-archived) conversations are never purged.
+
+When an archived conversation exceeds the retention period, it is deleted along
+with its messages, diff statuses, and queued messages via cascade. Orphaned
+files (not referenced by any active or recently-archived conversation) are also
+deleted. Both operations run in batches of 1,000 rows per cycle.
+
+## Configuration
+
+Navigate to **Deployment Settings** > **Agents** > **Behavior** to configure
+the conversation retention period. The default is 30 days. Use the toggle to
+disable retention entirely.
+
+The retention period is stored as the `agents_chat_retention_days` key in the
+`site_configs` table and can also be managed via the API at
+`/api/experimental/chats/config/retention-days`.
+
+## What gets deleted
+
+| Data                   | Condition                                                                                      | Cascade                                                       |
+|------------------------|------------------------------------------------------------------------------------------------|---------------------------------------------------------------|
+| Archived conversations | Archived longer than retention period                                                          | Messages, diff statuses, queued messages deleted via CASCADE. |
+| Conversation files     | Older than retention period AND not referenced by any active or recently-archived conversation | —                                                             |
+
+## Unarchive safety
+
+If a user unarchives a conversation whose files were purged, stale file
+references are automatically cleaned up by FK cascades. The conversation
+remains usable but previously attached files are no longer available.
+
+## Related links
+
+- [Coder Agents](./index.md)
+- [Data Retention](../../admin/setup/data-retention.md)