Until recently Avers has suffered from an unfortunate design decision that
I did in the initial storage layer design: The patches table alone did not
fully describe the contents of an object, you needed the initial snapshot which
was stored in the snapshots table (under
RevId 0). This caused some
operational problems as the snapshots table was not merely there for performance
optimization, but was an integral part that was needed for data consistency.
This limitation is now lifted for all new objects which you create with the
latest version of avers, or for objects for which you manually create
There is now a new type of patch: a
Set operation with path referring to the
root. It can be used to fully override the
contents of a snapshot. This patch is used in place of the initial snapshot,
and also for checkpoints (more on that later). The initial snapshot with
RevId 0 was replaced by this new patch (also with
RevId 0). In the absence
of any snapshot in the database, all patches are applied on an empty snapshot.
This works because the first available patch is guaranteed to initialize the
snapshot contents to a valid representation of the object.
Checkpoints are a mechanism to trim object history. A checkpoint patch has the same format as the initial patch. It makes all previous patches and snapshots obsolete so that they can be deleted. The deletion is not done automatically when you create a checkpoint, there is a separate function for that. That process is called vacuuming.
Interaction with Release objects
Avers does not prevent you from vacuuming object history which is
still referred to by a
Release object. I don't use
Release objects in my
projects, but when I do I'll need to figure out how exactly Avers should behave
in those situations.
createCheckpoint :: ObjectId -> Avers RevId
Use this function to create a checkpoint. You get the
RevId of the checkpoint
patch. It is safe to create checkpoints at any time. Though I suggest that you
create checkpoints only when you intend to trim the object history.
vacuumObject :: ObjectId -> Avers ()
Use this function to remove all patches and snapshots up until the latest checkpoint. Note that this will irrecoverably remove that history from the database.