Figaro - The XML Database for the .NET Framework

When upgrading databases to support a newer version of Berkeley DB, it may be necessary to upgrade the on-disk format of already-created database files. 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 procedures outlined in this guide should be carefully followed.

Note:

If you are not performing catastrophic archival as part of your application upgrade process, you should at least copy your database to archival media, verify that your archival media is error-free and readable, and that copies of your backups are stored offsite!

Database upgrades can be performed at the command-line level using db_upgrade or through the API using UpgradeContainer.

After an upgrade, Berkeley DB applications must be recompiled to use the new Berkeley DB library before they can 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. It is guaranteed that any archived database may be upgraded using a current Berkeley DB software release and the UpgradeContainer 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.

Upgrading Databases

The following information describes the general process of upgrading applications using the Figaro BDB XML library. There are four areas to be considered when upgrading Berkeley DB applications and database environments:

  • The application API
  • The database environment's region files
  • The underlying database formats
  • Log files (for transactional environments)

The upgrade procedures required depend on whether or not the release is a major or minor release (in which either the major or minor number of the version changed), or a patch release (in which only the patch number in the version changed). Figaro BDB major and minor releases may optionally include changes in all four areas; that is, the application API, region files, database formats, and log files may not be backward-compatible with previous releases. A Berkeley DB database formats in incompatible ways, and so applications may only need to be recompiled or reconfigured to point to the new assembly version.

Upgrading a Patch Release

  1. Shut down all applications using the Figaro library.

  2. Install the library update.

  3. Restart the applications.

Upgrading non-transactional environments

  1. Shut down all applications using the Figaro library.

  2. Remove any old environment using the Remove method or an appropriate system utility.

  3. Install the new version of the Figaro library.

  4. If necessary, upgrade the application databases.

  5. Restart the applications.

Upgrading transactional environments without upgrading log or database files

  1. Shut down all applications using the Figaro library.

  2. Run recovery on the database environment using the Open method (using the Recover option), or the db_recover utility.

  3. Remove any old environment using the Remove method or an appropriate system utility.

  4. Install the new version of the Figaro library.

  5. If necessary, upgrade the application databases.

  6. Restart the applications.

Upgrading transactional environments and log fileswithout upgrading database files

  1. Shut down all applications using the Figaro library.

  2. Run recovery on the database environment using the Open method (using the Recover option), or the db_recover utility.

  3. Archive the database environment for catastrophic recovery.

  4. Install the new version of the Figaro library.

  5. Force a checkpoint using the SetEnvironmentTransactionCheckpoint or the db_checkpoint utility. If you use the db_checkpoint utility, make sure to use the new version of the utility - that is, the version that came with the installation you are upgrading with.

  6. Restart the applications.

Upgrading transactional environments, log files and databases

  1. Shut down all applications using the Figaro library.

  2. Run recovery on the database environment using the Open method (using the Recover option), or the db_recover utility.

  3. Remove any old environment using the Remove method or an appropriate system utility.

  4. Archive the database environment for catastrophic recovery.

  5. Install the new version of the Figaro library.

  6. Upgrade the databases.

  7. Archive the database for catastrophic recovery again (using different media than before, of course). Note: This archival is not strictly necessary. However, if you have to perform catastrophic recovery after restarting the application, that recovery must be done based on the last archive you have made. If you make this second archive, you can use it as the basis of that catastrophic recovery. If you do not make this second archive, you have to use the archive you made in step 4 as the basis of your recovery, and you have to do a full upgrade on it before you can apply log files created after the upgrade to it.

  8. Force a checkpoint using the SetEnvironmentTransactionCheckpoint or the db_checkpoint utility. If you use the db_checkpoint utility, make sure to use the new version of the utility - that is, the version that came with the installation you are upgrading with.

  9. Restart the applications.

See Also