Merge branch 'main' from workbench2.git
[arvados.git] / doc / architecture / keep-data-lifecycle.html.textile.liquid
1 ---
2 layout: default
3 navsection: architecture
4 title: "Data lifecycle"
5 ...
6
7 {% comment %}
8 Copyright (C) The Arvados Authors. All rights reserved.
9
10 SPDX-License-Identifier: CC-BY-SA-3.0
11 {% endcomment %}
12
13 h2(#overview). Overview
14
15 Arvados collections consist of a "manifest":{{site.baseurl}}/architecture/manifest-format.html and the data blocks referenced in that manifest. Manifests are stored in the PosgreSQL database, @data blocks@ are stored by a @keepstore@.
16
17 Data blocks are frequently shared between collections. Each collection has its own @manifest@. Collection manifests and data blocks have a separate lifecycle, which is described in detail below.
18
19 h2(#collection_lifecycle). Collection lifecycle
20
21 During its lifetime, a collection can be in various states. These states are *persisted*, *expiring*, *trashed*  and *permanently deleted*.
22
23 The nominal state is *persisted* which means the data can be can be accessed normally and will be retained indefinitely.
24
25 A collection is *expiring* when it has a *trash_at* time in the future. An expiring collection can be accessed as normal, but is scheduled to be trashed automatically at the *trash_at* time.
26
27 A collection is *trashed* when it has a *trash_at* time in the past. The *is_trashed* attribute will also be "true". The delete operation immediately puts the collection in the trash by setting the *trash_at* time to "now", and *delete_at* defaults to "now" + @Collections.DefaultTrashLifetime@. Once trashed, the collection is no longer readable through normal data access APIs. The collection will have *delete_at* set to some time in the future. The trashed collection is recoverable until the *delete_at* time passes, at which point the collection is permanently deleted.
28
29 See "Recovering trashed collections":{{ site.baseurl }}/user/tutorials/tutorial-keep-collection-lifecycle.html#trash-recovery for instructions to recover trashed collections.
30
31 h3(#collection_attributes). Collection lifecycle attributes
32
33 As listed above the attributes that are used to manage a collection lifecycle are *is_trashed*, *trash_at*, and *delete_at*. The table below lists the values of these attributes and how they influence the state of a collection and its accessibility.
34
35 table(table table-bordered table-condensed).
36 |_. collection state|_. is_trashed|_. trash_at|_. delete_at|_. get|_. list|_. list?include_trash=true|_. can be modified|
37 |persisted collection|false |null |null |yes |yes |yes |yes |
38 |expiring collection|false |future |future |yes  |yes |yes |yes |
39 |trashed collection|true |past |future |no |no |yes |only is_trashed, trash_at and delete_at attributes|
40 |deleted collection|true|past |past |no |no |no |no |
41
42 h2(#block_lifecycle). Block lifecycle
43
44 During its lifetime, a data block can be in various states. These states are *persisted*, *unreferenced*, *trashed* and *permanently deleted*.
45
46 The nominal state is *persisted* which means the block can be can be retrieved normally from a @keepstore@ process.
47
48 A block is *unreferenced* when there are no collection manifests in the PostgreSQL collections table that reference it. The block can still be retrieved normally from a @keepstore@ process, e.g. by creating a new collection with a manifest that references the hash of the block. Unreferenced blocks will be moved to the *trashed* state by @keep-balance@ after @BlobSigningTTL@, if @BlobTrash@ is enabled and @keep-balance@ is running and configured to send trash lists to the keepstores.
49
50 A block is *trashed* when @keep-balance@ has asked a @keepstore@ to move it to its trash and @BlobTrash@ is enabled. It will stay there for a period of time, subject to the @BlobTrashLifetime@ settings.
51
52 A block is *permanently deleted* on the first wakeup of its @keepstore@ trash process after the block has spent @BlobTrashLifetime@ in that keepstore's trash. The trash process wakes up with a frequency defined by the @BlobTrashCheckInterval@.
53
54 table(table table-bordered table-condensed).
55 |_. block state|_. duration|_. retrievable via Keep|_. can be recovered|
56 |persisted block|indefinitely|yes |n/a |
57 |unreferenced block|@BlobSigningTTL@ + up to @BalancePeriod@ + duration of keep-balance run|yes |n/a |
58 |trashed block|@BlobTrashLifetime@ + up to @BlobTrashCheckInterval@|no |yes |
59 |deleted block||no |no |