Skip to main content

​
prefect.server.services.db_vacuum

The database vacuum service. Two perpetual services schedule cleanup tasks independently, gated by the enabled set in PREFECT_SERVER_SERVICES_DB_VACUUM_ENABLED (default ["events"]):
  1. schedule_vacuum_tasks — Cleans up old flow runs and orphaned resources (logs, artifacts, artifact collections). Enabled when "flow_runs" is in the enabled set.
  2. schedule_event_vacuum_tasks — Cleans up old events, including any event types with per-type retention overrides. Enabled when "events" is in the enabled set and event_persister.enabled is true (the default), so that operators who disabled event processing are not surprised on upgrade. Runs in all server modes, including ephemeral.
Per-event-type retention can be customised via PREFECT_SERVER_SERVICES_DB_VACUUM_EVENT_RETENTION_OVERRIDES. Event types not listed fall back to server.events.retention_period. Each task runs independently with its own error isolation and docket-managed retries. Deterministic keys prevent duplicate tasks from accumulating if a cycle overlaps with in-progress work.

​
Functions

​
schedule_vacuum_tasks 

schedule_vacuum_tasks(docket: Docket = CurrentDocket(), perpetual: Perpetual = Perpetual(automatic=False, every=timedelta(seconds=get_current_settings().server.services.db_vacuum.loop_seconds))) -> None
Schedule cleanup tasks for old flow runs and orphaned resources. Each task is enqueued with a deterministic key so that overlapping cycles (e.g. when cleanup takes longer than loop_seconds) naturally deduplicate instead of piling up redundant work. Disabled by default because it permanently deletes flow runs. Enable via PREFECT_SERVER_SERVICES_DB_VACUUM_ENABLED=true.

​
schedule_event_vacuum_tasks 

schedule_event_vacuum_tasks(docket: Docket = CurrentDocket(), perpetual: Perpetual = Perpetual(automatic=False, every=timedelta(seconds=get_current_settings().server.services.db_vacuum.loop_seconds))) -> None
Schedule cleanup tasks for old events and heartbeat events. Enabled by default ("events" is in the default enabled set). Automatically disabled when the event persister service is disabled (PREFECT_SERVER_SERVICES_EVENT_PERSISTER_ENABLED=false) so that operators who opted out of event processing are not surprised by trimming on upgrade.

​
vacuum_orphaned_logs 

vacuum_orphaned_logs() -> None
Delete logs whose flow_run_id references a non-existent flow run.

​
vacuum_orphaned_artifacts 

vacuum_orphaned_artifacts() -> None
Delete artifacts whose flow_run_id references a non-existent flow run.

​
vacuum_stale_artifact_collections 

vacuum_stale_artifact_collections() -> None
Reconcile artifact collections whose latest_id points to a deleted artifact. Re-points to the next latest version if one exists, otherwise deletes the collection row.

​
vacuum_old_flow_runs 

vacuum_old_flow_runs() -> None
Delete old top-level terminal flow runs past the retention period.

​
vacuum_events_with_retention_overrides 

vacuum_events_with_retention_overrides() -> None
Delete events whose types have per-type retention overrides. Iterates over all entries in event_retention_overrides and deletes events (and their resources) that are older than the configured retention for that type, capped by the global events retention period.

​
vacuum_old_events 

vacuum_old_events() -> None
Delete all events and event resources past the general events retention period.