16.8 Numsync Extension

In Crash recovery, we have shown that for database recovery, one should select the snapshot whose permission bits are read-only and whose last-modification timestamp is greatest. However, there may be cases when a crash occurs at such a time that both snapshot files remain readable. It may also happen, that their permissions had been reset to read-only and/or modification times inadvertently changed before recovery. To make it possible to select the right snapshot in such cases, a new extended database format was introduced in GDBM version 1.21. This format adds to the database header the numsync field, that holds the number of synchronizations the database underwent before being closed or abandoned due to a crash.

Each snapshot is an exact copy of the database at a given point of time. Thus, if both snapshots of a database in extended format are readable, it will suffice to examine their numsync counters and select the one whose numsync is greater. That’s what the gdbm_latest_snapshot function does in this case.

It is worth noticing, that the two counters should differ exactly by one. If the difference is greater than that, gdbm_latest_snapshot will return a special status code, GDBM_SNAPSHOT_SUSPICIOUS. If, during a recovery attempt, you get this status code, we recommend to proceed with the manual recovery, e.g. by examining both snapshot files using the snapshot command in gdbmtool (see gdbmtool).

To create a database in extended format, call gdbm_open with both GDBM_NEWDB and GDBM_NUMSYNC flags:

dbf = gdbm_open(dbfile, 0, GDBM_NEWDB|GDBM_NUMSYNC, 0600, NULL);

Notice, that this flag must always be used together with GDBM_NEWDB (see Open).

A standard GDBM database can be converted to the extended format. To convert an existing database to the extended format, use the gdbm_convert function (see Database format):

  rc = gdbm_convert(dbf, GDBM_NUMSYNC);

You can do the same using the gdbmtool utility (see upgrade):

gdbmtool dbname upgrade

The conversion is reversible. To convert a database from extended format back to the standard GDBM format, do:

  rc = gdbm_convert(dbf, 0);

To do the from the command line:

gdbmtool dbname downgrade