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 recover utility of the agtool 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. See the agtool general command utility document for information on the agtool program.
(In earlier releases there was an agraph-recover program. That program, along with most other command-line AllegroGraph programs, have been folded into the single agtool program.)
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 agtool agaph-backup program can change the uuid for a database it is restoring.
% agtool archive --newuuid restore dbname db.backup Since this is a common operation when doing point-in-time recovery, the agtool archive 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 agtool 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 agtool recover to show you all the recovery points.
% agtool recover --list --tlogdir tlog-archive-dir my-db In the command above we are asking for a brief list of commit points for the my-db database. The --tlogdir argument says that transaction log files we can use for recovery are found in the tlog-archive-dir subdirectory. (There is a current transaction log directory specified by the TransactionLogDir configuration directive and there may be archived transaction log files (see Transaction Log Archiving). --tlogdir can be specified more than once.
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:
% agtool recover --list --detail 8 --tlogdir tlog-archive-dir my-db
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.
% agtool recover --recover 15 --tlogdir tlog-archive-dir my-db
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:
- agtool recover --list [--detail <number>] [--tlogdir <dir>] [--port|-p <port>] [--catalog|-c <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:
- agtool recover --recover <number> [--tlogdir <dir>] [--port|-p <port>] [--catalog|-c <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.