Introduction

The content of Allegrograph database is the result of a sequence of commits, each commit being recorded in a transaction log as well as in other database files. You can make a backup of a database (even while it's running) and you then have a copy of the database at a certain point in time. Meanwhile the original database continues to be used and further commits are done and written to the transaction log.

If you restore the database backup you can view the state of the database as it was when the backup was done. This may not be what you want. You may want to see what it looked like a few hours or a few days later.

You can use the point-in-time recovery program to advance the state of the restored database forward to any later commit that was done to the original (and perhaps still running) database. It is as if you did a backup after every commit.

New UUID

If your purpose in doing point-in-time recovery is to bring the database to a certain state and then make use in a way where you'll be making new commits, then you should change the uuid of the database so that the transaction logs for this recovered database do not get confused with the transaction logs for the original database.

The agraph-backup program can change the uuid for a database it is restoring. 

% agraph-backup --newuuid restore dbname db.backup

Since this is a common operation when doing point-in-time recovery, the agraph-backup option --recover will set both --newuuid and --nocommit.

When you specify --newuuid, the restored backup has a new uuid and the original uuid is now in a file, parent-uuid, since the parent uuid will be needed by the agraph-recover program to find the old commits to add to this database.

Listing Commits

In order to find the point at which you want to advance your restored backup, use the program agraph-recover to show you all the recovery points. 

% agraph-recover --list --tlogdir trec.arch trec.rest

In the command above we are asking for a brief list of commit points for the trec.rest database. The --tlogdir argument says that transaction log files we can use for recovery are found in the trec.arch subdirectory.

The output of this command looks like the following: 

Computing the recovery points  
10 transaction logs available for recovery  
Recovery can be  
 from commit 6 at 2010-09-30T12:14:16-07:00  
   to commit 35 at 2010-09-30T12:23:25-07:00  
 
List of initial commits in each transaction log  
Log Number  Commit Number    Commit Time  
        6             6  2010-09-30T12:14:16-07:00  
        7            10  2010-09-30T12:15:20-07:00  
        8            14  2010-09-30T12:16:22-07:00  
       10            16  2010-09-30T12:19:35-07:00  
       13            26  2010-09-30T12:22:06-07:00  
 
Final Commit  
Log Number  Commit Number    Commit Time  
       13            35  2010-09-30T12:23:25-07:00

We can see that we can advance the database to a commit in the range commit 6 at 12:15:16 to commit 26 at 12:23:25.

We don't see log files 9, 11, and 12 listed. These log files contain no commit records.

We may decide that we want all the commits from log file number 8 listed. We use the --detail option for that: 

% agraph-recover --list --detail 8 --tlogdir trec.arch trec.rest  
 
Computing the recovery points  
10 transaction logs available for recovery  
Recovery can be  
 from commit 6 at 2010-09-30T12:14:16-07:00  
   to commit 35 at 2010-09-30T12:23:25-07:00  
 
List of initial commits in each transaction log  
Log Number  Commit Number    Commit Time  
        6             6  2010-09-30T12:14:16-07:00  
        7            10  2010-09-30T12:15:20-07:00  
        8            14  2010-09-30T12:16:22-07:00  
       10            16  2010-09-30T12:19:35-07:00  
       13            26  2010-09-30T12:22:06-07:00  
 
Final Commit  
Log Number  Commit Number    Commit Time  
       13            35  2010-09-30T12:23:25-07:00  
 
Details on transaction log file 8  
Log Number  Commit Number    Commit Time  
        8            14  2010-09-30T12:16:22-07:00  
        8            15  2010-09-30T12:16:38-07:00

Now we see the details at the end. The --detail argument and the --tlogdir argument may be given more than once.

Doing Recovery

Based on the information above we've decided to advance the database to commit 15. 

% agraph-recover --recover 15 --tlogdir trec.arch trec.rest  
Recover commit 6  
Recover commit 7  
Recover commit 8  
Recover commit 9  
Recover commit 10  
Recover commit 11  
Recover commit 12  
Recover commit 13  
Recover commit 14  
Recover commit 15

Reference

To plan your recovery strategy:

agraph-recover --list [--detail <number>] [--tlogdir <dir>] [--port <port>] [--catalog <catalog>] <dbname>
- Will list the first commit of all applicable transaction logs.
- Will list all the commits in the transaction log specified by --detail. Note that the detail argument can be given more than once.
- The tlogdir argument specifies a directory to search for transaction logs for the database that was backed up and restored to create this data base. The tlogdir argument may be given more than once.
- port specifies the listening port for the allegrograph server. this defaults to 10035.

To execute recovery:

agraph-recover --recover <number> [--tlogdir <dir>] [--port <port>] [--catalog <catalog>] <dbname>
- Advance the given database to the commit number given to the recover argument
- The tlogdir argument specifies a directory to search for transaction logs for the database that was backed up and restored to create this data base. The tlogdir argument may be given more than once.
- port specifies the listening port for the allegrograph server. This defaults to 10035.