# Run a Standalone Garbage Collector

> Learn how to run garbage collection as a separate process from your database clients

By default, SlateDB starts a background garbage collector inside each `Db` instance.
You can also run garbage collection as a separate service:

1. Keep your existing `Db` clients running.
2. Start one or more standalone garbage collectors against the same database path.

All processes must use the same `ObjectStore` and database path (the path is the prefix inside your object store).

Unlike the compactor coordinator, the garbage collector does not require fencing or leader election. Multiple garbage collectors may run in parallel, including the embedded collectors inside writer processes.

If you want a standalone process to own all garbage collection work, set `Settings::garbage_collector_options` to `None` in your `Db` clients.

## Run from the CLI

For a single foreground pass over one file type, use `run-garbage-collection`:

```bash
slatedb --env-file .env --path <db-path> run-garbage-collection \
  --resource compacted \
  --min-age 5m
```

Valid resources are `manifest`, `wal`, `wal-fence`, `compacted`, and `compactions`.

To run garbage collection on a schedule in a standalone process, pass one or more schedules:

```bash
slatedb --env-file .env --path <db-path> schedule-garbage-collection \
  --manifest min_age=5m,period=1m \
  --wal min_age=5m,period=1m \
  --compacted min_age=5m,period=1m \
  --compactions min_age=5m,period=1m
```

The scheduled process runs until interrupted (Ctrl-C), then shuts down gracefully.

The command above does not collect WAL fence objects. Enable `--wal-fence` only when `min_age` is longer than any writer can run. Default garbage collection keeps WAL fence deletion in dry-run mode because deleting fences too early can allow stale WAL writes to succeed.

## Embed the garbage collector

You can also embed the garbage collector in your own process using `GarbageCollectorBuilder` and call `run`:

<!-- could not inline /home/runner/work/slatedb/examples/src/standalone_garbage_collector.rs -->

With `GarbageCollectorOptions::default()`, garbage collection runs every 60 seconds and uses a 5 minute minimum age for managed directories. WAL fence deletion stays in dry-run mode by default.

:::note

The standalone garbage collector expects the database to already exist (a manifest must be present).
If you're creating a new database, open it once with your client process before starting the garbage collector.

Garbage collection deletes only files that meet the configured `min_age` and are no longer referenced by the latest database state or active checkpoints.

:::