Threadline.Retention (Threadline v1.0.0)

Threadline.Retention batches expiry of AuditChange rows and optionally removes empty AuditTransaction rows.

Requires config :threadline, :retention with enabled: true before any destructive run (see Threadline.Retention.Policy). Callers must pass repo: explicitly, matching the Threadline read functions.

Cutoff is derived from Threadline.Retention.Policy.cutoff_utc_datetime_usec!/0 unless you pass cutoff: (UTC DateTime, microsecond) for a stricter window than policy alone (operators only — must be older than the policy cutoff).

Summary

Types

purge_opt()

An option accepted by purge/1.

purge_result()

Accumulator returned by purge/1 on success (counts are cumulative).

Functions

purge(opts)

Returns purge_result() after deleting expired AuditChange rows, or {:error, :disabled} when retention is disabled. Raises ArgumentError for invalid policy or a cutoff newer than the policy cutoff; repository errors are reraised.

Types

purge_opt()

@type purge_opt() ::
  Threadline.repo_opt()
  | Threadline.storage_schema_opt()
  | {:batch_size, pos_integer()}
  | {:max_batches, pos_integer()}
  | {:dry_run, boolean()}
  | {:sleep_ms, non_neg_integer()}
  | {:cutoff, DateTime.t()}

An option accepted by purge/1.

purge_result()

@type purge_result() :: %{
  deleted_changes: non_neg_integer(),
  deleted_transactions: non_neg_integer(),
  batches_run: non_neg_integer(),
  dry_run: boolean()
}

Accumulator returned by purge/1 on success (counts are cumulative).

Functions

purge(opts)

@spec purge([purge_opt()]) :: purge_result() | {:error, :disabled}

The cutoff comes from Threadline.Retention.Policy; an explicit cutoff must be older than or equal to that policy cutoff.

Options

:repo — Ecto.Repo module. Required.
:storage_schema — string. Optional. Selects the Threadline storage schema.
:batch_size — positive integer. Defaults to 500; maximum rows per delete pass.
:max_batches — positive integer. Defaults to 10_000; maximum change batches plus orphan draining.
:dry_run — boolean. Defaults to false; when true, no deletes and returns counts of rows that would match delete predicates (:deleted_changes / :deleted_transactions are those counts, :batches_run is 0). The preview assumes the run completes; a run cut short by :max_batches deletes fewer. :batch_size and :max_batches are ignored in dry-run mode — the preview is a single full-table count, not a batched simulation, so passing either alongside dry_run: true has no effect on the returned counts.
:sleep_ms — non-negative integer. Defaults to 50; delay between delete batches.
:cutoff — UTC DateTime. Optional. Must be at or before the policy cutoff.

Other option keys are ignored.

Returns

purge_result() — cumulative deletion counts and whether the run was a dry run.
{:error, :disabled} — the retention policy does not have enabled: true.
Raises ArgumentError for invalid policy or a cutoff newer than the policy cutoff; repository errors are reraised.