From 2a5d86e2aaad211188591a5f28480a891c0e034f Mon Sep 17 00:00:00 2001
From: david-fraley <67079030+david-fraley@users.noreply.github.com>
Date: Sun, 2 Nov 2025 19:12:37 -0600
Subject: [PATCH] docs: add vacuum full on `audit logs` table recommendation
 (#20608)

---
 docs/admin/security/audit-logs.md | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/docs/admin/security/audit-logs.md b/docs/admin/security/audit-logs.md
index 387bdd9836..75c349aee2 100644
--- a/docs/admin/security/audit-logs.md
+++ b/docs/admin/security/audit-logs.md
@@ -151,6 +151,36 @@ Should you wish to purge these records, it is safe to do so. This can only be do
 directly against the `audit_logs` table in the database. We advise users to only purge old records (>1yr)
 and in accordance with your compliance requirements.
 
+### Maintenance Procedures for the Audit Logs Table
+
+> [!NOTE]
+> `VACUUM FULL` acquires an exclusive lock on the table, blocking all reads and writes. For more information, see the [PostgreSQL VACUUM documentation](https://www.postgresql.org/docs/current/sql-vacuum.html).
+
+You may choose to run a `VACUUM` or `VACUUM FULL` operation on the audit logs table to reclaim disk space. If you choose to run the `FULL` operation, consider the following when doing so:
+
+- **Run during a planned mainteance window** to ensure ample time for the operation to complete and minimize impact to users
+- **Stop all running instances of `coderd`** to prevent connection errors while the table is locked. The actual steps for this will depend on your particular deployment setup. For example, if your `coderd` deployment is running on Kubernetes:
+
+  ```bash
+  kubectl scale deployment coder --replicas=0 -n coder
+  ```
+
+- **Terminate lingering connections** before running the `VACUUM` operation to ensure it starts immediately
+
+  ```sql
+  SELECT pg_terminate_backend(pg_stat_activity.pid)
+  FROM pg_stat_activity
+  WHERE pg_stat_activity.datname = 'coder' AND pid <> pg_backend_pid();
+  ```
+
+- **Only `coderd` needs to scale down** - external provisioner daemons, workspace proxies, and workspace agents don't connect to the database directly.
+
+After the vacuum completes, scale coderd back up:
+
+```bash
+kubectl scale deployment coder --replicas= -n coder
+```
+
 ### Backup/Archive
 
 Consider exporting or archiving these records before deletion: