Berkeley DB Reference Guide: Upgrading Berkeley DB Applications

Upgrading Berkeley DB installations

The following information describes the general process of upgrading Berkeley DB installations. There are three issues to be considered when upgrading Berkeley DB applications and database environments. They are the application API, the underlying database formats, and, in the case of transactional database environments, the log files.

An application must always be re-compiled to use a new Berkeley DB release. Internal Berkeley DB interfaces may change at any time and in any release, without warning. This means the application and library must be entirely recompiled and reinstalled when upgrading to new releases of the library, as there is no guarantee that modules from one version of the library will interact correctly with modules from another release.

A Berkeley DB patch release will never modify the Berkeley DB API, log file or database formats in non-backward compatible ways. Berkeley DB minor and major releases may optionally include changes to the Berkeley DB application API, log files and database formats that are not backward compatible. Note, that there are several underlying Berkeley DB database formats. As all of them do not necessarily change at the same time, changes to one database format in a release may not affect any particular application.

Each Berkeley DB minor or major release has an upgrading section in this chapter of the Berkeley DB Reference Guide. The section describes any API changes that were made in the release. Application maintainers must review the API changes, update their applications as necessary, and then re-compile using the new release. In addition, each section includes a page specifying if the log file format or database formats changed in non-backward compatible ways as part of the release.

If the application does not have a Berkeley DB transactional environment, the re-compiled application may be installed in the field using the following steps:

1. Shut down the old version of the application.

2. Remove any Berkeley DB environment, using the DBENV->remove function or an appropriate system utility.

3. Install the new version of the application.

4. If the database format has changed, upgrade the application's databases. See Upgrading databases for more information.

5. Re-start the application.

If the application has a Berkeley DB transactional environment, but neither the log file or database formats have changed, the re-compiled application may be installed in the field using the following steps:

1. Shut down the old version of the application.

2. Run recovery on the database environment, using the DBENV->open function or the db_recover utility.

3. Install the new version of the application.

4. Re-start the application.

If the application has a Berkeley DB transactional environment, and the log file format has changed but the database formats have not, the re-compiled application may be installed in the field using the following steps:

1. Shut down the old version of the application.

2. Run recovery on the database environment, using the DBENV->open function or the db_recover utility.

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

4. Install the new version of the application.

5. Re-start the application.

If the application has a Berkeley DB transactional environment and the database format has changed, the re-compiled application may be installed in the field using the following steps:

1. Shut down the old version of the application.

2. Run recovery on the database environment, using the DBENV->open function or the db_recover utility.

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

4. Install the new version of the application.

5. Upgrade the application's databases. See Upgrading databases for more information.

6. 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.

7. Re-start the application.

Copyright Sleepycat Software