Database Revision Control - The Database Time Machine

Using Database Document Revisions and Revert Revisions for Most Recovery Tasks

Though DBAs are not necessarily famous for their shy vocabulary, the worst word they may utter remains that small “oops” following their realization that an erroneous operation, say a wrong patch or query, has wreaked havoc in the database.

A sigh of relief may follow such an incident, knowing the database is properly backed up and the damage can be nullified. However, restoring the database from a backup may take a long time, especially if the database is large, and cause the loss of all changes made after the creation of the latest backup.

Restoring the database for such a price may sometimes be just as harmful as the damage we want to fix, leaving us with a real dilemma.

One of the roles of RavenDB’s revision-control features, Document Revisions, and Revert Revisions, is to complement Backup and Restore in a way that rids us of such dilemmas. We can use these features to instantly revert specific documents or the entire database to their state at any chosen point in time, without having to restore the entire database.

Document Revisions and Revert Revisions

Revision control features are not only a means of recovery though: they also allow us to review a continuous timeline of documents’ development. Being able to tour the database history back and forth in time and instantly return it to any of its former states, frees us to alter documents using patches, queries, and other operations, without fearing possible consequences.

The Document Revisions feature allows us to record and review changes made in documents and instantly restore any document to any of its past revisions.

The Revert Revisions feature expands Document Revisions, allowing instant reversion of the entire database to its state at any point in time we choose without requiring a lengthy restore process.

Let’s start with a brief overview of backups and the cost of their restoration, so we can appreciate the benefits of revision control features.

Database Backup and Restore

RavenDB excels in backing up and restoring database contents. Designated cluster nodes run as many backup tasks as needed in the background, creating Full and Incremental backups and storing them locally or remotely for easy restoration. Many additional options, e.g. encrypting our backups, are available as well.

But restoring the database from a backup does present us with a few obstacles.

Downtime: The restoration procedure must bring the live database down to reinstate a backed-up copy of it. This suspension of service may cause a mild inconvenience to some users and real damage to others, depending on downtime length, users' and applications' tolerance to it, and other factors.
Data Gaps: Backups do not contain the full history of documents. A document may change many times between backup intervals without leaving any trace of these changes. The obvious and most painful example of it is the changes we’ve made since the creation of the latest backup which would be lost if we restore it. Old document versions may also be lost. Though most data corruption incidents are discovered soon enough, some are not (e.g., ones that affect rarely-used documents or document parts). When we do find out about them, backups that precede the incident may have already been considered outdated and deleted to free backup storage space.
Disproportionate Risk: We sometimes need to revert only a few documents to their former state. Restoring the entire database and affecting a huge number of documents and all users, seems disproportionate and even risky on such occasions.

Luckily, restoring from a backup is no longer our only option. We can still resort to it when we must, but turn to Document Revisions and Revert Revisions for most recovery tasks. These two revision-control features allow us to keep a continuous, live timeline of each document’s past versions (a.k.a. “Revisions”), easily browse the timeline, and instantly revert documents to any of their revisions or the whole database to a chosen point in time.

Document Revisions

When the Document Revisions feature is enabled, the database creates a copy (“revision”) of each document each time the document is updated, to keep a continuous timeline of its development.

We can then tour through the document’s past revisions, and instantly revert its live version to any of them with no additional restoration procedure and without affecting any other document.

The number of revisions the database is allowed to keep for each document is configurable, enabling us to maintain as comprehensive a history of the document as we like.

Revisions are kept separately from document contents, to prevent them from slowing down document updating and delivery. However, a document’s revisions are still regarded as a part of it (like other document extensions such as counters, time series, and attachments) and can be, among other operations, replicated and backed up along with the document they belong to.

Revert Revisions

The Revert Revisions feature expands our ability to revert documents, to the scope of the entire database. Instead of reverting a single document, you can now instantly roll back the entire database to its state at a chosen Point in Time.

Documents updated after the chosen Point in Time will be reverted to their latest revisions before the PiT. (Technically, the historical revision is duplicated and the new copy is set as the present revision.)
Documents created after the chosen PiT will be deleted (and remain salvable in the revisions bin).
Documents that haven’t changed since the PiT are left untouched.

Like the single-document reversion it is founded upon, Revert Revisions take very little time and require no additional restoration procedure, taking no toll on service.

In a typical scenario, documents that require reversion due to, for example, an erroneous patch or query, are discovered and reverted shortly after the event. When this is the case, a vast majority of the documents require no handling, and the resources needed to conduct the procedure remain negligible.

Auditing procedures, with their contribution to proper administration, can be conducted document-by-document using Document Revisions, by inspecting the revisions trail a document leaves behind.

But documents are often interrelated, and the reason behind a document update is often easier to reveal when the document is situated in its original environment. Thus, using the Revert Revisions “time machine” to easily thumb through the entire database as it had been at various points in time, is a great auditing tool.

A DBA who justly hesitates to run even simple patches over the database without an option to undo the changes may provide such services without hesitation knowing they can be reverted in a click of a button.

And a click of a button is, indeed, all it takes; an unpresuming button in RavenDB’s Studio Document Revisions section, whose looks reveal little of its enormous capacity.

Revert Revisions

To revert the entire database to its state at a certain point in time, simply click the Revert Revisions button and provide the point in time to revert to.