History retention#

The history plugin purges old entity history. The stardust/history setting of an entity states how much of its history to keep. Enable it at open with plugins {history {}} to use the default schedule. See plugin selection for the open options.

The history and backups plugins cannot share a database. History retention rewrites the transaction chain that backups must preserve.

Setting#

Write stardust/history on an entity with a merge patch or a mutation, like any other field:

{
  "#_log": {
    "name": "Log",
    "stardust/history": {
      "retain": {
        "#dur": "P30D"
      },
      "cascade": true
    }
  }
}

The value must be a map with retain and an optional cascade, and no other member. Other values fail with the rejected status and the code invalid. Write null to remove the setting. Deleting the entity also removes its setting.

Descendants are the entities below it in the path tree, through stardust/path/parent. A descendant with its own setting uses that setting. A descendant without one uses the nearest ancestor setting that has cascade true. An own setting without cascade applies to that entity only: its children still use the cascading setting above it. Data entities that a merge patch creates have no children, so cascade has no effect on them.

Parent cycles#

If stardust/path/parent links form a cycle, each cascade walk visits an entity at most once. The plugin skips repeated entities and does not report the cycle as an error. Purging continues with the resolved retention settings. An entity's own setting still overrides an inherited setting.

Purge timing#

retain selects the history to remove during a later purge. Until that purge finishes, older facts or more than N transactions can remain. The plugin purges after commits settle, in bounded steps.

Synchronization#

Retention runs automatically according to the schedule. This plugin provides no sync operation. A plugin_call of sync on "history" reports invalid_argument with code unknown_operation.

What a purge removes#

A purge removes facts completely. Purged facts cannot be recovered.

• Each field of the entity keeps its state at the purge bound. A read as of an earlier transaction sees that oldest kept state. No read fails.
• History at or after the bound does not change.
• The newest transaction of the database is never purged. A setting never removes the current state.
• Definitions are never purged.
• Purged space is reused for later writes. The database file does not shrink.

Schedule#

Supply schedule settings in the history load settings when opening the database:

{
  "history": {
    "debounce": {
      "#dur": "PT2S"
    },
    "max_wait": {
      "#dur": "PT30S"
    },
    "recheck": {
      "#dur": "PT1M"
    }
  }
}

These settings are durations. Negative values and unknown setting names fail before the database opens. An empty settings object uses all defaults. Settings apply to this open database and are not stored on entities.

A commit that changes a retention setting, or touches an entity that a setting covers, starts the schedule. The next purge is due at the earlier deadline: debounce after the last such commit, or max_wait after the first. The committer runs it when admission and queue capacity allow. The plugin checks duration settings again after recheck, also without commits. Open starts the same schedule, so purging resumes after a restart.

Live reactors#

The reactors plugin evaluates each live mutation as of the transaction it reacts to. While a live mutation has not processed a transaction, the purge keeps every fact from that transaction on. The rest of the purge waits until the reactor cursor moves past it. The plugin then checks again after recheck.

Without the plugin#

On a database that does not enable history, a write that sets stardust/history fails with the unavailable status and the code plugin_required. Removing a setting is always accepted. A setting stored while the plugin was enabled stays, but nothing is purged until the plugin is enabled again.