Collection version history¶

(draft)

Background: desired API features (#13494, #13561) epic ticket is #13109

• Get current + previous versions of a collection with a single API call
• Search all current + previous versions of collections with a single API call
• Stable small numeric "version number" for each version of a given collection

Design¶

• Store all versions in the collection table (much easier to do paging)
• New database column "current_version_uuid" for latest version this the same as "uuid"
• New database column indicates user-friendly version number (starting at 1) -- can be assigned safely after locking "current" row for update
• Assign version number to the current version -- this way {uuid,version} can be used as a permanent reference to a specific version
• Flag "include_past_versions" for "list" API to include old versions (otherwise, filter on current_version_uuid=uuid -- might need to adjust indexes to maintain performance)
• Flag in site configuration to enable preserving old versions in database
• Update owner_uuid of all old versions (in a transaction) when it changes in the current version
• A permission link to the current version only implies permission to the most recent version (not the history)
• Prohibit permission links to old versions (should be handled by check "can only make links to things that are visible to you", which should not include old versions)
• Old versions may not be modified except for certain fields which must be synchronized with "current" version changes (owner_uuid, trash_at, delete_at). Updating owner_uuid, trash_at, delete_at does not update modified_at so modified_at shows when the version was created
• Old versions with duplicate "name" does not conflict with (owner_uuid, name) uniqueness constraint
• The following changes introduce a new version: manifest_text (portable_data_hash), description, properties, name,
• The following changes do not introduce a new version, and a copied to all past version records: replication_*, storage_classes_*, trash_at/delete_at/is_trashed, owner_uuid, uuid (update current_uuid to retain database consistency)
• If the existing version is less than N (site-configurable) minutes old, and has not been explicitly flagged via new API ("commit"?), it is not retained in the version history.
  • (PA proposal) add a field "checkpoint_at", which means this version will be checkpointed if an update occurs after checkpoint_at. Update operations can set {checkpoint_at: 1970-01-01} or use ?checkpoint_after=0 to ensure a version will be checkpointed. When updating a collection, the checkpoint_at field is reset to modified_at + value of the parameter checkpoint_after provided by the client, or the system default.
  • (TC proposal) add a boolean field "preserve_version", which defaults to false on create/update. During an update, save a snapshot in the version history if preserve_version || (current_timestamp - modified_at > config.version_batch_timeout).