Automatic Purging

Automatic purging removes old CoreProtect data on a daily schedule, helping keep database growth under control without requiring manual /co purge runs.

Note: Automatic purging is not enabled by default. This feature is exclusive to CoreProtect 24.0+ Patreon builds.

Configuration

To enable automatic purging, set auto-purge in config.yml to the amount of data you want to keep:

auto-purge: 180d

This example keeps the most recent 180 days of CoreProtect data and automatically removes older data.

Supported values use the same style as CoreProtect command times, such as 30d, 12w, or 6mo. The minimum automatic purge value is 30d. Set auto-purge: false to disable automatic purging.

Schedule

Automatic purging runs once per day using your server's local time. By default, it runs at midnight.

To change the daily runtime, manually add auto-purge-time: 03:30 to config.yml.
Use 24-hour HH:mm server time.

After changing auto-purge or auto-purge-time, use /co reload or restart the server. Changes apply to the next scheduled run.

When automatic purging is enabled, CoreProtect logs the next scheduled run when the server starts and again after an automatic purge completes.

How It Works

Automatic purging runs in the background. SQLite, MySQL, and DuckDB remove old rows incrementally in small chunks with short pauses between database work. ClickHouse uses its columnar retention path, dropping fully covered monthly partitions for an unfiltered time purge and synchronously removing rows from any partially covered partition.

Automatic purging does not rebuild SQLite, optimize MySQL, or run a ClickHouse OPTIMIZE FINAL. DuckDB performs a checkpoint after cleanup. Deleting rows helps control future growth, but it may not immediately reduce the database file or table size on disk.

Only one automatic purge can run at a time. If the server shuts down, a manual purge starts, a database migration or conversion starts, or the consumer is manually paused, the automatic purge stops safely and can continue during the next scheduled run.

Important Notes

  • Patreon exclusive: Only available in CoreProtect 24.0+ Patreon builds
  • Not enabled by default: Set auto-purge in config.yml to enable automatic purging
  • Background cleanup: Automatic purging is designed to run while the server remains usable

Existing Databases

If enabling automatic purging on a new database, no additional action is required.

If enabling automatic purging on an existing database, it is recommended to run a manual purge first using the same time value:

/co purge t:180d

For MySQL, add #optimize if you want to reclaim disk space during the initial manual purge:

/co purge t:180d #optimize

This lets the manual purge reduce the existing database size, while automatic purging helps keep the database from growing beyond the configured retention period afterward.

ClickHouse normally reclaims complete old partitions without #optimize. A manual ClickHouse purge accepts #optimize, but it runs the expensive OPTIMIZE TABLE ... FINAL operation and is generally unnecessary. DuckDB checkpoints automatically after a manual or automatic purge; #optimize has no additional effect for DuckDB.

Status

Use /co status to see how many rows have been automatically purged since the last server restart.

Troubleshooting

Automatic purging won't start:

  • Verify you're using a CoreProtect 24.0+ Patreon build
  • Verify auto-purge is set to a valid value of at least 30d
  • Check the server console for automatic purge scheduling messages