prefect.server.services.db_vacuum

The database vacuum service. Three 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, then deletes their logs and artifacts by flow_run_id in bounded batches. 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.

3. schedule_orphan_vacuum_tasks — Cleans up logs and artifacts orphaned by interrupted cleanup, late writes, direct SQL deletion, or older Prefect versions. It runs daily when flow run vacuum is enabled, rather than on the hourly vacuum loop, and can also be enabled independently with "orphans".

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 ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/db_vacuum.py#L133" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

schedule_vacuum_tasks(docket: Docket = CurrentDocket(), perpetual: Perpetual = Perpetual(automatic=True, every=timedelta(seconds=get_current_settings().server.services.db_vacuum.loop_seconds))) -> None

Schedule cleanup tasks for old flow runs.

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 ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/db_vacuum.py#L162" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

schedule_event_vacuum_tasks(docket: Docket = CurrentDocket(), perpetual: Perpetual = Perpetual(automatic=True, 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.

schedule_orphan_vacuum_tasks ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/db_vacuum.py#L191" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

schedule_orphan_vacuum_tasks(docket: Docket = CurrentDocket(), perpetual: Perpetual = Perpetual(automatic=True, every=timedelta(seconds=get_current_settings().server.services.db_vacuum.orphan_cleanup_loop_seconds))) -> None

Schedule lower-frequency orphan reconciliation tasks.

Each pass can scan the full log and artifact tables, so this service runs less often than the normal flow run and event vacuum loops.

vacuum_orphaned_logs ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/db_vacuum.py#L217" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

vacuum_orphaned_logs() -> None

Delete logs whose flow_run_id references a non-existent flow run.

vacuum_orphaned_artifacts ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/db_vacuum.py#L238" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

vacuum_orphaned_artifacts() -> None

Delete artifacts whose flow_run_id references a non-existent flow run.

vacuum_stale_artifact_collections ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/db_vacuum.py#L259" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

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 ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/db_vacuum.py#L280" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

vacuum_old_flow_runs() -> None

Delete old top-level terminal flow runs past the retention period.

log and artifact have no ON DELETE CASCADE from flow_run. Each run batch is selected and deleted in one locking transaction, then its children are deleted by flow_run_id using indexed lookups.

batch_size bounds how many runs are selected, not how many children they have, so children are deleted in separately committed batches rather than in one transaction with the runs and their cascaded task runs and states. Deleting the runs first prevents a concurrent state transition from preserving a run after some of its children were permanently deleted. If child cleanup is interrupted, orphan reconciliation recovers it.

vacuum_events_with_retention_overrides ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/db_vacuum.py#L347" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

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 ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/services/db_vacuum.py#L401" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

vacuum_old_events() -> None

Delete all events and event resources past the general events retention period.