sqlite_graphrag/commands/
purge.rs

1//! Handler for the `purge` CLI subcommand.
2
3use crate::errors::AppError;
4use crate::i18n::errors_msg;
5use crate::output;
6use crate::paths::AppPaths;
7use crate::storage::connection::open_rw;
8use serde::Serialize;
9
10#[derive(clap::Args)]
11#[command(after_long_help = "EXAMPLES:\n  \
12    # Permanently delete soft-deleted memories older than 90 days (default retention)\n  \
13    sqlite-graphrag purge\n\n  \
14    # Custom retention window in days\n  \
15    sqlite-graphrag purge --retention-days 30\n\n  \
16    # Purge ALL soft-deleted memories regardless of age\n  \
17    sqlite-graphrag purge --retention-days 0\n\n  \
18    # Preview what would be purged without deleting\n  \
19    sqlite-graphrag purge --dry-run\n\n  \
20    # Purge a specific memory by name\n  \
21    sqlite-graphrag purge --name old-memory --namespace my-project\n\n\
22NOTES:\n  \
23    `--yes` only confirms intent and does NOT override `--retention-days`.\n  \
24    To wipe every soft-deleted memory immediately, pair `--yes` with `--retention-days 0`.")]
25pub struct PurgeArgs {
26    #[arg(long)]
27    pub name: Option<String>,
28    /// Namespace to purge. Defaults to the contextual namespace (SQLITE_GRAPHRAG_NAMESPACE env var or "global").
29    #[arg(long)]
30    pub namespace: Option<String>,
31    /// Retention days: memories with deleted_at older than (now - retention_days*86400) will be
32    /// permanently removed. Default: PURGE_RETENTION_DAYS_DEFAULT (90). Use 0 to purge all
33    /// soft-deleted memories regardless of age. Alias: `--max-age-days`.
34    #[arg(
35        long,
36        alias = "days",
37        alias = "max-age-days",
38        value_name = "DAYS",
39        default_value_t = crate::constants::PURGE_RETENTION_DAYS_DEFAULT
40    )]
41    pub retention_days: u32,
42    /// [DEPRECATED in v2.0.0] Legacy alias — use --retention-days instead.
43    #[arg(long, hide = true)]
44    pub older_than_seconds: Option<u64>,
45    /// Does not execute DELETE: computes and reports what WOULD be purged.
46    #[arg(long, default_value_t = false)]
47    pub dry_run: bool,
48    /// Confirms destructive intent for tools that require explicit acknowledgement.
49    /// Does NOT override `--retention-days`: combine with `--retention-days 0` to wipe
50    /// every soft-deleted memory regardless of age.
51    #[arg(long, default_value_t = false)]
52    pub yes: bool,
53    #[arg(long, hide = true, help = "No-op; JSON is always emitted on stdout")]
54    pub json: bool,
55    #[arg(long, env = "SQLITE_GRAPHRAG_DB_PATH")]
56    pub db: Option<String>,
57}
58
59#[derive(Serialize)]
60pub struct PurgeResponse {
61    pub action: String,
62    pub purged_count: usize,
63    pub bytes_freed: i64,
64    pub oldest_deleted_at: Option<i64>,
65    pub retention_days_used: u32,
66    pub dry_run: bool,
67    pub namespace: Option<String>,
68    pub cutoff_epoch: i64,
69    pub warnings: Vec<String>,
70    /// Total execution time in milliseconds from handler start to serialisation.
71    pub elapsed_ms: u64,
72    /// Human-readable explanation surfaced when nothing was purged so callers
73    /// understand the retention semantics. Present only when
74    /// `purged_count == 0` (M2 in v1.0.32) — kept absent otherwise to preserve
75    /// the existing JSON contract.
76    #[serde(skip_serializing_if = "Option::is_none")]
77    pub message: Option<String>,
78}
79
80/// Permanently delete soft-deleted memories that have exceeded the retention window.
81///
82/// Only memories with `deleted_at IS NOT NULL AND deleted_at <= cutoff_epoch` are affected.
83/// When `--dry-run` is set the DELETE is skipped and the response reflects candidates only.
84pub fn run(args: PurgeArgs) -> Result<(), AppError> {
85    let inicio = std::time::Instant::now();
86    let namespace = crate::namespace::resolve_namespace(args.namespace.as_deref())?;
87    let paths = AppPaths::resolve(args.db.as_deref())?;
88
89    crate::storage::connection::ensure_db_ready(&paths)?;
90
91    let mut warnings: Vec<String> = Vec::with_capacity(1);
92    let now = current_epoch()?;
93
94    let cutoff_epoch = if let Some(secs) = args.older_than_seconds {
95        warnings.push(
96            "--older-than-seconds is deprecated; use --retention-days in v2.0.0+".to_string(),
97        );
98        now - secs as i64
99    } else {
100        now - (args.retention_days as i64) * 86_400
101    };
102
103    let namespace_opt: Option<&str> = Some(namespace.as_str());
104
105    let mut conn = open_rw(&paths.db)?;
106
107    let (bytes_freed, oldest_deleted_at, candidates_count) =
108        compute_metrics(&conn, cutoff_epoch, namespace_opt, args.name.as_deref())?;
109
110    if candidates_count == 0 && args.name.is_some() {
111        return Err(AppError::NotFound(
112            errors_msg::soft_deleted_memory_not_found(
113                args.name.as_deref().unwrap_or_default(),
114                &namespace,
115            ),
116        ));
117    }
118
119    if !args.dry_run && !args.yes {
120        return Err(AppError::Validation(
121            "destructive operation: pass --yes to confirm purge (use --dry-run to preview)"
122                .to_string(),
123        ));
124    }
125
126    if !args.dry_run {
127        let tx = conn.transaction_with_behavior(rusqlite::TransactionBehavior::Immediate)?;
128        execute_purge(
129            &tx,
130            &namespace,
131            args.name.as_deref(),
132            cutoff_epoch,
133            &mut warnings,
134        )?;
135        tx.commit()?;
136        conn.execute_batch("PRAGMA wal_checkpoint(TRUNCATE);")?;
137    }
138
139    let message = if candidates_count == 0 {
140        Some(format!(
141            "no soft-deleted memories older than {retention_days} day(s); use --retention-days 0 to purge all soft-deleted memories regardless of age",
142            retention_days = args.retention_days
143        ))
144    } else {
145        None
146    };
147
148    output::emit_json(&PurgeResponse {
149        action: if args.dry_run {
150            "dry_run".to_string()
151        } else {
152            "purged".to_string()
153        },
154        purged_count: candidates_count,
155        bytes_freed,
156        oldest_deleted_at,
157        retention_days_used: args.retention_days,
158        dry_run: args.dry_run,
159        namespace: Some(namespace),
160        cutoff_epoch,
161        warnings,
162        elapsed_ms: inicio.elapsed().as_millis() as u64,
163        message,
164    })?;
165
166    Ok(())
167}
168
169fn current_epoch() -> Result<i64, AppError> {
170    let now = std::time::SystemTime::now()
171        .duration_since(std::time::UNIX_EPOCH)
172        .map_err(|err| AppError::Internal(anyhow::anyhow!("system clock error: {err}")))?;
173    Ok(now.as_secs() as i64)
174}
175
176fn compute_metrics(
177    conn: &rusqlite::Connection,
178    cutoff_epoch: i64,
179    namespace_opt: Option<&str>,
180    name: Option<&str>,
181) -> Result<(i64, Option<i64>, usize), AppError> {
182    let (bytes_freed, oldest_deleted_at): (i64, Option<i64>) = if let Some(name) = name {
183        conn.query_row(
184            "SELECT COALESCE(SUM(LENGTH(COALESCE(body,'')) + LENGTH(COALESCE(description,'')) + LENGTH(name)), 0),
185                    MIN(deleted_at)
186             FROM memories
187             WHERE deleted_at IS NOT NULL AND deleted_at <= ?1
188                   AND (?2 IS NULL OR namespace = ?2)
189                   AND name = ?3",
190            rusqlite::params![cutoff_epoch, namespace_opt, name],
191            |r| Ok((r.get::<_, i64>(0)?, r.get::<_, Option<i64>>(1)?)),
192        )?
193    } else {
194        conn.query_row(
195            "SELECT COALESCE(SUM(LENGTH(COALESCE(body,'')) + LENGTH(COALESCE(description,'')) + LENGTH(name)), 0),
196                    MIN(deleted_at)
197             FROM memories
198             WHERE deleted_at IS NOT NULL AND deleted_at <= ?1
199                   AND (?2 IS NULL OR namespace = ?2)",
200            rusqlite::params![cutoff_epoch, namespace_opt],
201            |r| Ok((r.get::<_, i64>(0)?, r.get::<_, Option<i64>>(1)?)),
202        )?
203    };
204
205    let count: usize = if let Some(name) = name {
206        conn.query_row(
207            "SELECT COUNT(*) FROM memories
208             WHERE deleted_at IS NOT NULL AND deleted_at <= ?1
209                   AND (?2 IS NULL OR namespace = ?2)
210                   AND name = ?3",
211            rusqlite::params![cutoff_epoch, namespace_opt, name],
212            |r| r.get::<_, usize>(0),
213        )?
214    } else {
215        conn.query_row(
216            "SELECT COUNT(*) FROM memories
217             WHERE deleted_at IS NOT NULL AND deleted_at <= ?1
218                   AND (?2 IS NULL OR namespace = ?2)",
219            rusqlite::params![cutoff_epoch, namespace_opt],
220            |r| r.get::<_, usize>(0),
221        )?
222    };
223
224    Ok((bytes_freed, oldest_deleted_at, count))
225}
226
227fn execute_purge(
228    tx: &rusqlite::Transaction,
229    namespace: &str,
230    name: Option<&str>,
231    cutoff_epoch: i64,
232    warnings: &mut Vec<String>,
233) -> Result<(), AppError> {
234    let candidates = select_candidates(tx, namespace, name, cutoff_epoch)?;
235
236    for (memory_id, _name) in &candidates {
237        if let Err(err) = tx.execute(
238            "DELETE FROM vec_chunks WHERE memory_id = ?1",
239            rusqlite::params![memory_id],
240        ) {
241            warnings.push(format!(
242                "failed to clean vec_chunks for memory_id {memory_id}: {err}"
243            ));
244        }
245        if let Err(err) = tx.execute(
246            "DELETE FROM vec_memories WHERE memory_id = ?1",
247            rusqlite::params![memory_id],
248        ) {
249            warnings.push(format!(
250                "failed to clean vec_memories for memory_id {memory_id}: {err}"
251            ));
252        }
253        tx.execute(
254            "DELETE FROM memories WHERE id = ?1 AND namespace = ?2 AND deleted_at IS NOT NULL",
255            rusqlite::params![memory_id, namespace],
256        )?;
257    }
258
259    Ok(())
260}
261
262fn select_candidates(
263    conn: &rusqlite::Connection,
264    namespace: &str,
265    name: Option<&str>,
266    cutoff_epoch: i64,
267) -> Result<Vec<(i64, String)>, AppError> {
268    let query = if name.is_some() {
269        "SELECT id, name FROM memories
270         WHERE namespace = ?1 AND name = ?2 AND deleted_at IS NOT NULL AND deleted_at <= ?3
271         ORDER BY deleted_at ASC"
272    } else {
273        "SELECT id, name FROM memories
274         WHERE namespace = ?1 AND deleted_at IS NOT NULL AND deleted_at <= ?2
275         ORDER BY deleted_at ASC"
276    };
277
278    let mut stmt = conn.prepare_cached(query)?;
279    let rows = if let Some(name) = name {
280        stmt.query_map(rusqlite::params![namespace, name, cutoff_epoch], |row| {
281            Ok((row.get::<_, i64>(0)?, row.get::<_, String>(1)?))
282        })?
283        .collect::<Result<Vec<_>, _>>()?
284    } else {
285        stmt.query_map(rusqlite::params![namespace, cutoff_epoch], |row| {
286            Ok((row.get::<_, i64>(0)?, row.get::<_, String>(1)?))
287        })?
288        .collect::<Result<Vec<_>, _>>()?
289    };
290    Ok(rows)
291}
292
293#[cfg(test)]
294mod tests {
295    use super::*;
296    use rusqlite::Connection;
297
298    fn setup_test_db() -> Connection {
299        let conn = Connection::open_in_memory().expect("failed to open in-memory db");
300        conn.execute_batch(
301            "CREATE TABLE memories (
302                id INTEGER PRIMARY KEY AUTOINCREMENT,
303                name TEXT NOT NULL,
304                namespace TEXT NOT NULL DEFAULT 'global',
305                description TEXT,
306                body TEXT,
307                deleted_at INTEGER
308            );
309            CREATE TABLE IF NOT EXISTS vec_chunks (memory_id INTEGER);
310            CREATE TABLE IF NOT EXISTS vec_memories (memory_id INTEGER);",
311        )
312        .expect("failed to create test tables");
313        conn
314    }
315
316    fn insert_deleted_memory(
317        conn: &Connection,
318        name: &str,
319        namespace: &str,
320        body: &str,
321        deleted_at: i64,
322    ) -> i64 {
323        conn.execute(
324            "INSERT INTO memories (name, namespace, body, deleted_at) VALUES (?1, ?2, ?3, ?4)",
325            rusqlite::params![name, namespace, body, deleted_at],
326        )
327        .expect("failed to insert test memory");
328        conn.last_insert_rowid()
329    }
330
331    #[test]
332    fn retention_days_used_default_is_90() {
333        assert_eq!(crate::constants::PURGE_RETENTION_DAYS_DEFAULT, 90u32);
334    }
335
336    #[test]
337    fn compute_metrics_bytes_freed_positive_for_populated_body() {
338        let conn = setup_test_db();
339        let now = current_epoch().expect("epoch failed");
340        let old_epoch = now - 100 * 86_400;
341        insert_deleted_memory(&conn, "mem-test", "global", "memory body", old_epoch);
342
343        let cutoff = now - 30 * 86_400;
344        let (bytes, oldest, count) =
345            compute_metrics(&conn, cutoff, Some("global"), None).expect("compute_metrics failed");
346
347        assert!(bytes > 0, "bytes_freed must be > 0 for populated body");
348        assert!(oldest.is_some(), "oldest_deleted_at must be Some");
349        assert_eq!(count, 1);
350    }
351
352    #[test]
353    fn compute_metrics_returns_zero_without_candidates() {
354        let conn = setup_test_db();
355        let now = current_epoch().expect("epoch failed");
356        let cutoff = now - 90 * 86_400;
357
358        let (bytes, oldest, count) =
359            compute_metrics(&conn, cutoff, Some("global"), None).expect("compute_metrics failed");
360
361        assert_eq!(bytes, 0);
362        assert!(oldest.is_none());
363        assert_eq!(count, 0);
364    }
365
366    #[test]
367    fn dry_run_does_not_delete_records() {
368        let conn = setup_test_db();
369        let now = current_epoch().expect("epoch failed");
370        let old_epoch = now - 200 * 86_400;
371        insert_deleted_memory(&conn, "mem-dry", "global", "dry run content", old_epoch);
372
373        let cutoff = now - 30 * 86_400;
374        let (_, _, count_before) =
375            compute_metrics(&conn, cutoff, Some("global"), None).expect("compute_metrics failed");
376        assert_eq!(count_before, 1, "must have 1 candidate before dry run");
377
378        let (_, _, count_after) =
379            compute_metrics(&conn, cutoff, Some("global"), None).expect("compute_metrics failed");
380        assert_eq!(
381            count_after, 1,
382            "dry_run must not remove records: count must remain 1"
383        );
384    }
385
386    #[test]
387    fn oldest_deleted_at_returns_smallest_epoch() {
388        let conn = setup_test_db();
389        let now = current_epoch().expect("epoch failed");
390        let epoch_old = now - 300 * 86_400;
391        let epoch_recent = now - 200 * 86_400;
392
393        insert_deleted_memory(&conn, "mem-a", "global", "body-a", epoch_old);
394        insert_deleted_memory(&conn, "mem-b", "global", "body-b", epoch_recent);
395
396        let cutoff = now - 30 * 86_400;
397        let (_, oldest, count) =
398            compute_metrics(&conn, cutoff, Some("global"), None).expect("compute_metrics failed");
399
400        assert_eq!(count, 2);
401        assert_eq!(
402            oldest,
403            Some(epoch_old),
404            "oldest_deleted_at must be the oldest epoch"
405        );
406    }
407
408    #[test]
409    fn purge_args_namespace_accepts_none_without_default() {
410        // P1-C: namespace must be None when not provided, allowing resolve_namespace
411        // to consult SQLITE_GRAPHRAG_NAMESPACE before falling back to "global".
412        // The field was `default_value = "global"` before P1-C; with that removed,
413        // resolve_namespace(None) consults the env var correctly.
414        let resolved = crate::namespace::resolve_namespace(None)
415            .expect("resolve_namespace(None) must return Ok");
416        assert_eq!(
417            resolved, "global",
418            "without env var, resolve_namespace(None) must fall back to 'global'"
419        );
420    }
421
422    #[test]
423    fn purge_response_serializes_all_new_fields() {
424        let resp = PurgeResponse {
425            action: "purged".to_string(),
426            purged_count: 3,
427            bytes_freed: 1024,
428            oldest_deleted_at: Some(1_700_000_000),
429            retention_days_used: 90,
430            dry_run: false,
431            namespace: Some("global".to_string()),
432            cutoff_epoch: 1_710_000_000,
433            warnings: vec![],
434            elapsed_ms: 42,
435            message: None,
436        };
437        let json = serde_json::to_string(&resp).expect("serialization failed");
438        assert!(json.contains("bytes_freed"));
439        assert!(json.contains("oldest_deleted_at"));
440        assert!(json.contains("retention_days_used"));
441        assert!(json.contains("dry_run"));
442        assert!(json.contains("elapsed_ms"));
443        // M2: when no purge happened, `message` is omitted to keep payloads stable.
444        assert!(!json.contains("\"message\""));
445    }
446
447    #[test]
448    fn purge_response_serializes_message_when_present() {
449        // M2 (v1.0.32): zero purges include a human-readable hint message.
450        let resp = PurgeResponse {
451            action: "purged".to_string(),
452            purged_count: 0,
453            bytes_freed: 0,
454            oldest_deleted_at: None,
455            retention_days_used: 90,
456            dry_run: false,
457            namespace: Some("global".to_string()),
458            cutoff_epoch: 1_710_000_000,
459            warnings: vec![],
460            elapsed_ms: 5,
461            message: Some(
462                "no soft-deleted memories older than 90 day(s); use --retention-days 0 to purge all soft-deleted memories regardless of age"
463                    .to_string(),
464            ),
465        };
466        let json = serde_json::to_string(&resp).expect("serialization failed");
467        assert!(json.contains("\"message\""));
468        assert!(json.contains("--retention-days 0"));
469    }
470}
sqlite_graphrag/commands/purge.rs

sqlite_graphrag/commands/
purge.rs
