MapGuide RFC 23 - Berkeley DB XML 2.3 Upgrade

This page contains a change request (RFC) for the MapGuide Open Source project. More MapGuide RFCs can be found on the RFCs page.

Status

RFC Template Version	(1.0)
Submission Date	July 3, 2007
Last Modified	Steve Dang Timestamp
Author	Steve Dang
RFC Status	implemented
Implementation Status	completed
Proposed Milestone	2.0
Assigned PSC guide(s)	(when determined)
Voting History	July 24, 2007
+1	Tom, Jason, Andy, Bob, Haris, Bruce
+0
-0
-1
Abstained	Paul

Overview

This RFC updates MapGuide to use the latest version of Berkeley DB XML.

For details, refer to Berkeley DB XML 2.3 release notes:

​http://www.oracle.com/technology/documentation/berkeley-db/xml/relnotes.html

Motivation

There was some report from the user group that the MapGuide repositories got corrupted (though recoverable). The Berkeley DB XML 2.3 upgrade could help minimize such incident.

The benefits of Berkeley DB XML 2.3 release include conformance to W3C recommendations for XQuery 1.0 and XPath 2.0, bug fixes, and performance improvements:

​http://www.oracle.com/technology/documentation/berkeley-db/xml/change-log.html

Proposed Solution

Modifications need to be made to the MapGuide server and its installer:

1. The server will detect a version mismatch at startup, and throw an exception along with instructions on how to upgrade.

Like other exceptions thrown at startup time, this Version Mismatch exception will stop the server from running:

• If the server is running as a service, then the error will be logged and available to the user for viewing (i.e. via the server log file or the event viewer).
• If the server is running as an application, then the error will be logged and displayed on the console/terminal window.

The error message will include a brief description about the problem and a reference to the detailed upgrade documentation.

2. During setup, the installer will back up the existing repositories if necessary, then run the upgrade utilities (which will do nothing if the repositories have already been upgraded). In rare/complex situation, the installer may encounter some upgrade problem (e.g. different combinations of versions of repositories, including no longer supported ones, etc.). When this happens, the installer will continue the installation without the upgrade, and at the end, it will display a brief description about the problem and a reference to the detailed upgrade documentation. Note that, the installer will need to install the upgrade utilities so that they can be run independently at a later time. This is useful when:

• The version mismatch detected by the server or the upgrade problem encountered by the installer does occur.
• The user would like to restore previously backed up repositories, then upgrade them without rerunning the installer.

Here are the manual steps on how to upgrade the repositories:

1. Shut down the existing MapGuide Server (e.g. "1.2.x") if it is running.

2. Change to the RepositoryAdmin directory (e.g. "C:\Program Files\MapGuideOpenSource\Server\RepositoryAdmin\" or "/usr/local/mapguide/server/RepositoryAdmin/").

3. Run BackUpOnlineRepositories.bat (or BackUpOnlineRepositories.sh).

4. Run RestoreRepositories.bat (or RestoreRepositories.sh).

5. Un-install the existing MapGuide Server. Note that the existing repositories will not get removed.

6. Install the new MapGuide Server (e.g. "2.0.0"). Note that the Server will fail to start if it tries to open old repositories.

7. Shut down the newly installed Server if it started successfully (because it created new repositories on a different location).

8. If the new MapGuide Server is installed on a different location than the old one, delete the Repositories directory then copy/move the old one to the new location (e.g. "C:\Program Files\MapGuideOpenSource\Server\Repositories\" or "/usr/local/mapguide/server/Repositories/").

9. Change to the RepositoryAdmin directory (e.g. "C:\Program Files\MapGuideOpenSource\Server\RepositoryAdmin\" or "/usr/local/mapguide/server/RepositoryAdmin/").

10. Run UpgradeRepositories.bat (or UpgradeRepositories.sh).

11. Run SetupRepositoryIndices.bat (or SetupRepositoryIndices.sh).

12. Restart the Server. It should successfully open the upgraded repositories.

Note that the upgrade could take longer time if you have large repositories.

Implications

• The database format has been changed and there is no way to revert the upgrade, so the repositories must be backed up.
• There have been 5 patches for Berkeley DB XML 2.3 release which will be included with the upgrade:

​http://www.oracle.com/technology/products/berkeley-db/xml/update/2.3.10/patch.2.3.10.html

• Any new Berkeley DB XML defect found during development will be fixed and reported to Oracle.

Test Plan

Tests need to be done after the upgrade:

• Resource Service unit tests must all pass.
• Scripts that back up, restore, and recover repositories must run successfully.

Funding/Resources

Supplied by Autodesk.