Berkeley DB Reference Guide: Access Method Operations

Upgrading databases

When upgrading to a new release of Berkeley DB, it may be necessary to upgrade the on-disk format of already-created database files.

It is important to realize that Berkeley DB database upgrades are done in place, and so are potentially destructive. This means that if the system crashes during the upgrade procedure, or if the upgrade procedure runs out of disk space, the databases may be left in an inconsistent and unrecoverable state.

To guard against failure, the following procedure should be followed:

1. Cleanly shutdown database operations.

   To cleanly shutdown database operations, all applications accessing the database environment must be shutdown and a transaction checkpoint must be taken. If the applications are not implemented such that they can be shutdown gracefully (i.e., closing all references to the database environment and taking a database checkpoint), recovery must be performed after all applications have been killed to ensure that the underlying databases are consistent and up-to-date on disk.

2. Archive the database for catastrophic recovery. See Archival procedures for more information.

3. Upgrade the database using the DB->upgrade method, or by dumping the database using the old version of the Berkeley DB software and reloading it using the current version. If this process fails for any reason, use the catastrophic recovery archive to restore the database.

4. Archive the database for catastrophic recovery again (using different media than before, of course).

   This archival is not strictly necessary. However, if you have to perform catastrophic recovery after restarting your applications, that recovery must be done based on the last archive you have made. If you make this archive, you can use it as the basis of your catastrophic recovery. If you do not make this archive, you will have to use the archive you made in step #2 as the basis of your recovery, and you will have to upgrade it as described in step #3 before you can apply your log files to it.

5. Restart database applications.

After an upgrade, Berkeley DB applications must be recompiled to use the new Berkeley DB library before they access an upgraded database. There is no guarantee that applications compiled against previous releases of Berkeley DB will work correctly with an upgraded database format. Nor is there any guarantee that applications compiled against newer releases of Berkeley DB will work correctly with the previous database format. We do guarantee that any archived database may be upgraded using a current Berkeley DB software release and the DB->upgrade method, and there is no need to step-wise upgrade the database using intermediate releases of Berkeley DB. Sites should consider archiving appropriate copies of their application or application sources if they may need to access archived databases without first upgrading them.

Copyright Sleepycat Software