Versioning bundle
The versioning bundle will create snapshots for every document upon every update made to it, or when it is deleted. It is useful when you need to track history of documents, or when you need a full audit trail.
As with all bundles, installation is as easy as just dropping Raven.Bundles.Versioning.dll into the plugins directory.
Configuration
By default, the Versioning bundle will track history for all documents and never purge old revisions. This is easily configurable by creating or changing configuration documents like this:
session.Store(new
{
Exclude = false,
Id = "Raven/Versioning/DefaultConfiguration",
MaxRevisions = 5
});
In this example is a global configuration document, telling the versioning bundle to version all documents (Exclude=false), and to only keep up to 5 revisions - purging older ones (MaxRevisions=5).
It is possible to override the behavior of the Versioning Bundle for a set of documents by creating a document specifically for an entity name. For example, let us say that we don't want to version users, we can tell the Versioning Bundle to avoid doing so adding a configuration document that is specific to the Users collection:
session.Store(new
{
Exclude = true,
Id = "Raven/Versioning/Users",
});
The naming convention used is "Raven/Versioning/" + entityName, where the entity name is the value of the Raven-Entity-Name property on the document.
Conversely, we can also set the default configuration to not version (Exclude = false), and configure versioning for each set of documents individually, by adding a document for each collection that we do want to version.
How it works
With the Versioning Bundle installed, let us execute this code:
using (var session = store.OpenSession())
{
session.Store(new User { Name = "Ayende Rahien" });
session.SaveChanges();
}
If we inspect the server, we will see the following documents were created:
The first document is the actual document that we just saved, we can see that it has a few additional metadata property than the ones we are used to:
- Raven-Document-Revision - The document revision (starts at 1).
- Raven-Document-Revision-Status - Whatever it is the Current revision or a Historical snapshot.
Now, let us modify the original document. This will give us:
As you can see, we have full audit record of all the changes that were made to the document.
You can access each of the revisions by simply using its id "users/1/revisions1". However, modifications / deletions of revisions are not allowed, and will result in an error if attempted.
Now, let us delete the original document:
That removed the current document, but the snapshots will remain in place, so you aren't going to lose the audit trail if the document is deleted.
As you can see, the Versioning Bundle attempts to make things as simple as possible, and once it is installed, you'll automatically get the appropriate audit trail. Working with revisions is identical to working with standard documents (except that you can't modify / delete them) and revision documents can be indexed like standard documents.
Limitations
- Versioning will fail on documents with keys larger than 230 characters.
- Versioning will not attempt to version internal Raven document (documents whose key starts with "Raven/")
Client integration
The Versioning bundle also have a client side part, which you can access by adding a reference to Raven.Client.Versioning assembly.
You can then access past revisions of a document using the following code:
var pastRevisions = session.Advanced.GetRevisionsFor<Loan>(loan.Id, 0, 25);
The comments section is for user feedback or community content. If you seek assistance or have any questions, please post them at our support forums.
If I delete an entity, the version info is still there, but how would I ever find it? When I query for entitities, those ids would not be in the results. I would have to specifically know the id, right?
Also, what if I did want to query against the version info? Is there a way to build an index on the versioned documents?
Yes, the version info is there. You would need to know the id of the root entity to know how to look for this, yes. You can't query on versioned snapshots, and there isn't a way to generate a query for that, no.