Skip to main content

Prune archived data

Learn how to remove archived objects and tokens from Vault​

The Vault object life cycle provides for archiving objects and tokens. When the retention period for archived items expires, you can remove them from Vault with a background prune job or manually using an API operation or CLI command.

note

By default, Vault retains archived items for 30 days. You set the retention period for archived objects and tokens with the PVAULT_DB_GC_RETENTION_PERIOD database environment variable.

Configuring the prune job​

note

If you're using the hosted version of Vault, contact us to set up the prune job.

To remove archived items at the end of their retention period, Vault includes a prune job that can be run automatically in the background.

The PVAULT_SERVICE_ARCHIVE_PRUNE_INTERVAL service and features environment variable determines how often the prune job runs. By default, this is set to 0, meaning the prune job does not run.

To activate the prune job, set PVAULT_SERVICE_ARCHIVE_PRUNE_INTERVAL to how frequently you want it to run. You can define the frequency in nanoseconds, microseconds, milliseconds, seconds, minutes, or hours. However, running the job more frequently than xx is not recommended.

Pruning objects in tokens manually​

You prune objects, tokens, and token transaction IDs with no associated tokens from Vault on demand using the delete objects and tokens API operation or CLI command.

Dry run​

Before pruning archived objects or tokens or token transaction IDs with no associated tokens, you can obtain a count of the items available for pruning by performing a dry run.

You do this using the CLI like this:

pvault admin gc --dry-run

You get a response similar to this:

+-----------------+-----------------+-------+
| collection_name | collection_type | count |
+-----------------+-----------------+-------+
| Tokens          | TOKENS          |   634 |
| buyers          | PERSONS         |  2751 |
| TransactionIDs  | TRANSACTION_IDS |     0 |
+-----------------+-----------------+-------+

You can also limit the dry run to only objects (--objects-only), tokens (--tokens-only), or token transaction IDs with no associated tokens (--transaction-ids-only).

With the REST API, you have to specify whether the dry run is for objects, tokens, or token transaction IDs with no associated tokens. For example, you do a dry run for tokens like this:

curl --request POST \
	--url 'http://localhost:8123/api/pvlt/1.0/system/admin/lifecycle/gc?filter=tokens_only&dry_run=true&reason=AppFunctionality' \
	--header 'Authorization: Bearer pvaultauth'

You get a response similar to this:

[
  {
    "collection_name": "Tokens",
    "collection_type": "TOKENS",
    "count": 634
  }
]

Performing a prune​

Using the REST API or CLI, you can prune archived items or token transaction IDs with no associated tokens from Vault. However, there are some notable differences between these two options.

  • The CLI deletes all candidate items in one call.
  • The REST API operation deletes a maximum of 10,000 items. To delete all items, repeat calls until the count of deleted items reaches zero. Using the prune job, rather than calling the API, is recommended.

Before performing a prune, the CLI prompts for confirmation. However, you can suppress this with the --force or -f flags. You can suppress any output with the --quiet flag when using the --force option. For example, in the CLI, you could prune all tokens without a challenge and with no output like this:

pvault admin gc --tokens-only --force --quiet

Whereas in the API, you prune tokens like this:

curl --request POST \
	--url 'http://localhost:8123/api/pvlt/1.0/system/admin/lifecycle/gc?filter=tokens_only&reason=AppFunctionality' \
	--header 'Authorization: Bearer pvaultauth'

You get a response similar to this:

[
  {
    "collection_name": "Tokens",
    "collection_type": "TOKENS",
    "count": 634
  }
]

On this page