17.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, which holds the number of synchronizations the database underwent before being closed or abandoned due to a crash.

A readable snapshot is a consistent 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 (see Manual crash recovery).

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). It is silently ignored when used together with another opening flag.

A standard GDBM database can be converted to the extended format and vice versa. 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

To convert a database from extended format back to the standard GDBM format, do:

  rc = gdbm_convert(dbf, 0);

To do the same from the command line, run:

gdbmtool dbname downgrade