Sun Java Enterprise System 5 Update 1 Upgrade Guide for UNIX |
Chapter 8
Java DBThis chapter describes how to upgrade Java DB to Java ES 5 Update 1 (Release 5U1): Java DB 10.2.2. It covers both feature upgrades from previous Java ES release families and maintenance upgrades from Java ES 5.
The chapter provides an overview of upgrade considerations for the different upgrade paths supported by Release 5U1. The chapter covers upgrades on both the Solaris and Linux operating systems:
Overview of Java DB UpgradesThis section describes the following general aspects of Java DB that impact upgrading to Java ES 5 Update 1 (Release 5U1):
About Release 5U1
Release 5U1 Java DB is a maintenance release that fixes bugs in Release 5 Java DB and provides some minor enhancements, such as support for JDBC 4. Some enhancements require conversion to a new data format.
Release 5U1 Upgrade Roadmap
Table 8-2 shows the supported Java DB upgrade paths to Release 5U1. The table applies to both Solaris and Linux operating systems.
Java DB Data
The following table shows the type of data that could be impacted by an upgrade of Java DB software.
Java DB Upgrade Strategy
Your strategy for upgrading Java DB generally depends on the many considerations discussed in Chapter 1, "Planning for Upgrades": upgrade path, dependencies between Java ES components, selective upgrade versus upgrade all, multi-instance deployments, and so forth.
This section is to particularize that general discussion to Java DB by presenting issues that might influence your Java DB upgrade plan.
Compatibility Issues
Release 5U1 Java DB is backwardly compatible with the Release 5 and Release 4 versions. However, to take full advantage of the enhanced functionality of Release 5U1 Java DB, you must convert data to the Java DB 10.2 disk format, which is incompatible with previous Java DB versions.
Dependencies
Java DB has a dependency only on the J2SE shared component (see Table 1-10).
Dual Upgrade
Dual upgrades, in which both Java DB and operating system are upgraded (as described in Dual Upgrades: Java ES and Operating System Software) can be performed in either of two ways:
Fresh Operating System Installation
- Back up existing Java DB data.
See Java DB Data for the location of essential data.
- Install the new operating system.
The operating system installation can be on a new system (or a Solaris 10 zone) or it can wipe out the existing file system.
- Install Release 5U1 Java DB.
- Restore the Java DB data that was backed up in Step 1.
In-place Operating System Upgrade
- Back up existing Java DB data.
See Java DB Data for the location of essential data.
- Upgrade the operating system.
The upgrade leaves the existing file system in place.
- Upgrade to Release 5U1 Java DB.
See the Upgrading Java DB from Java ES Release 4.
Java DB data should remain unaffected by the upgrade.
Upgrading Java DB from Java ES 5This section includes information about upgrading Java DB from Java ES 5 (Release 5) to Java ES 5 Update 1 (Release 5U1). The section covers the following topics:
Introduction
When upgrading Release 5 Java DB to Release 5U1, consider the following aspects of the upgrade process:
- General Upgrade Approach. The upgrade is achieved by patching Release 5 Java DB.
- Upgrade Dependencies. Java DB has dependencies on the Java SE shared component (see Table 1-10), which does not need to be upgraded when you perform a maintenance upgrade of Java DB.
- Backward Compatibility. Release 5UI Java DB is backwardly compatible with the Release 5 version, however the Release 5UI Java DB data format is not compatible with previous Java DB versions.
- Upgrade Rollback. A rollback of the Release 5U1 upgrade is achieved on Solaris OS by backing out the patch upgrade, but on the Linux platform rollback is achieved by manually reinstalling previous RPM packages.
- Platform Issues. The general approach for upgrading Java DB is the same on both Solaris and Linux operating systems.
Release 5 Java DB Upgrade
This section describes how to perform an upgrade of Java DB from Java ES Release 5 to Release 5U1 on both the Solaris and Linux platform. Where a topic depends on platform-specific procedures, the topic will indicate the operating system to which it applies. The section covers the following topics:
Pre-Upgrade Tasks
Before you upgrade Java DB software you should perform the following tasks:
Verify Current Version Information
You can verify the current version of Java DB using the following command:
java -cp JavaDB-base/lib/derby.jar org.apache.derby.tools.sysinfo
The version information (for the derby.jar file) is shown in the following table:
Table 8-4 Java DB Version Verification Outputs
Java ES Release
Java DB Version Number
Release 4
10.0.2.1
Release 5
10.1.3.1
Release 5U1
10.2.2.1
Upgrade Java DB Dependencies
It is generally recommended that all Java ES components on a computer system (and in a computing environment) be upgraded to Release 5U1. Release 5U1 Java DB has no hard upgrade dependencies, so upgrade of shared components is optional.
Back Up Java DB Data
The Java DB upgrade from Release 5 to Release 5U1 does not modify configuration data, but might require conversion of persistent data to a new format. Therefore, it is recommended that you back up your entire Java DB installation and your data before upgrading Java DB. See Table 8-3.
Obtain Required Configuration Information and Passwords
No configuration information or password is required to upgrade Java DB.
Upgrading Release 5 Java DB (Solaris)
This section discusses considerations that impact the upgrade procedure for Java DB, followed by a description of the procedure itself.
Upgrade Considerations (Solaris)
The upgrade of Java DB software to Java ES Release 5U1 takes into account the following considerations:
- In a deployment architecture in which there are multiple instances of Java DB running on a single computer (all corresponding to the same installed Java DB image), you only have to upgrade the Java DB image once.
- In a maintenance upgrade, you do not have to migrate schema, configuration, security or user data.
- The Release 5U1 Java DB upgrade patches for Solaris OS are shown in the following table:
Table 8-5 Patches1 to Upgrade Java DB on Solaris
Description
Patch ID: SPARC
Solaris 9 & 10
Patch ID: X86
Solaris 9 & 10
Java DB
125245-03
125246-02
1Patch revision numbers are the minimum required for upgrade to Release 5U1. If newer revisions become available, use the newer ones instead of those shown in the table.
Upgrade Procedure (Solaris)
The procedure documented below applies to Java DB instances residing locally on the computer where the upgrade is taking place.
- Log in as root or become superuser.
su -
- Stop Release 5 Java DB.
If you have a network server running, use the following command:
java -cp JavaDB-base/lib/derby.jar:JavaDB-base/lib/derbynet.jar org.apache.derby.drda.NetworkServerControl shutdown
Otherwise, simply shut down all applications using Java DB.
- Obtain the latest Java DB upgrade patches, based on Table 8-5.
To obtain the patch, see Accessing Java ES Patches. Patches can be downloaded to /workingDirectory.
- Apply the appropriate Java DB core patch in Table 8-5.
patchadd /workingDirectory/patch_ID
Be sure to consult the README.patch_ID file for additional patch installation instructions.
- Confirm that the patch upgrades were successful:
showrev -p | grep patch_ID
The output should return the versions of patch IDs applied in Step 4.
- Restart Release 5U1 Java DB.
If you are using a network server, use the following command:
java -jar <JavaDB-base>/lib/derbynet.jar start
Otherwise, simply start any application using Java DB in embedded mode.
Upgrading Release 5 Java DB (Linux)
This section discusses considerations that impact the upgrade procedure for Java DB, followed by a description of the procedure itself.
Upgrade Considerations (Linux)
The upgrade of Java DB software to Java ES Release 5U1 on the Linux platform takes into account the same considerations as on the Solaris platform (see Upgrade Considerations (Solaris)), except that the Linux Release 5U1 upgrade patches differ from the Solaris patches.
The Release 5U1 Java DB upgrade patches for Linux OS are shown in the following table:
Table 8-6 Patches1 to Upgrade Java DB on Linux
Description
Patch ID and RPM names
Java DB
125270-03
- sun-javadb-client-10.2.2-1.2.i386.rpm
- sun-javadb-common-10.2.2-1.2.i386.rpm
- sun-javadb-core-10.2.2-1.2.i386.rpm
- sun-javadb-demo-10.2.2-1.2.i386.rpm
- sun-javadb-derby2javadblnk-10.2.2-1.3.i386.rpm
- sun-javadb-docs-10.2.2-1.2.i386.rpm
- sun-javadb-javadoc-10.2.2-1.2.i386.rpm
- sun-javadb-usr-10.2.2-1.3.i386.rpm
1Patch revision numbers are the minimum required for upgrade to Release 5U1. If newer revisions become available, use the newer ones instead of those shown in the table.
Upgrade Procedure (Linux)
The procedure documented below applies to Java DB instances residing locally on the computer where the upgrade is taking place.
- Log in as root or become superuser.
su -
- Stop Release 5 Java DB.
If you have a network server running, use the following command:
java -cp JavaDB-base/lib/derby.jar:JavaDB-base/lib/derbynet.jar org.apache.derby.drda.NetworkServerControl shutdown
Otherwise, simply shut down all applications using Java DB.
- Obtain the latest Java DB upgrade patches, based on Table 8-6.
To obtain the patch, see Accessing Java ES Patches. Patches can be downloaded to /workingDirectory.
- Apply the core patch for Java DB in Table 8-6.
cd /workingDirectory/patch_ID
./installpatchIf installpatch reports any errors, you will need to resolve the reported errors and run installpatch again.
Be sure to consult the README.patch_ID file for additional patch installation instructions.
- Confirm that the patch upgrades were successful.
rpm -qa | grep sun-javadb
The new version numbers of the RPMs should be returned.
- Restart Release 5U1 Java DB.
If you are using a network server, use the following command:
java -jar <JavaDB-base>/lib/derbynet.jar start
Otherwise, simply start any application using Java DB in embedded mode.
Verifying the Upgrade
You can verify successful upgrade of Java DB using the following command:
java -cp JavaDB-base/lib/derby.jar org.apache.derby.tools.sysinfo
See Table 8-4 for output values (for the version of the derby.jar file).
Post-Upgrade Tasks
When upgrading Release 5 Java DB to Release 5U1, you must convert data from the Java DB 10.1 disk format to the 10.2 format if you want to take full advantage of the enhanced functionality of Release 5U1 Java DB.
To perform this conversion, connect to the database with upgrade=true appended to the JDBC URL. For example:
java -cp JavaDB-base/lib/derbytools.java:JavaDB-base/lib/derby.jar
org.apache.derby.tools.ijij version 10.2
ij> connect 'jdbc:derby:/databasePath;upgrade=true';
ij> exit;
For more information, see the Getting Started Guide in the docs directory of your Java DB installation.
Rolling Back the Upgrade (Solaris)
This section describes the Release 5U1 upgrade rollback procedure for Java DB on the Solaris platform.
- Log in as root or become superuser.
su -
- Stop Release 5U1 Java DB.
If you have a network server running, use the following command:
java -cp JavaDB-base/lib/derby.jar:JavaDB-base/lib/derbynet.jar org.apache.derby.drda.NetworkServerControl shutdown
Otherwise, simply shut down all applications using Java DB.
- Remove the patches in Table 8-5.
patchrm patch_ID
- If you have converted data to the Release 5U1 format, restore the Release 5 data.
- Start Release 5 Java DB.
If you are using a network server, use the following command:
java -jar <JavaDB-base>/lib/derbynet.jar start
Otherwise, simply start any application using Java DB in embedded mode.
Rolling Back the Upgrade (Linux)
This section describes the Release 5U1 upgrade rollback procedure for Java DB on the Linux platform. There is no automated rollback procedure for Linux patches, so the recommended approach is to manually overwrite the Release 5U1 RPMs with the Release 5 RPMs, as described below.
- Log in as root or become superuser.
su -
- Stop Release 5U1 Java DB.
If you have a network server running, use the following command:
java -cp JavaDB-base/lib/derby.jar:JavaDB-base/lib/derbynet.jar org.apache.derby.drda.NetworkServerControl shutdown
Otherwise, simply shut down all applications using Java DB.
- Check the revision numbers of Java DB RPMs.
rpm -qa | grep sun-javadb
The updated RPMs should be those listed in Table 8-6.
- Check to see if the RPMs have been relocated from their default location.
rpm -q --queryformat '%{INSTALLPREFIX}' rpmName
where rpmName is the unique name of the RPM (for example, the values sun-javadb-* shown in Table 8-6). The command returns a prefixValue as a path to the installed RPM.
- Reinstall Release 5 RPMs from the Java ES 5 distribution.
(If you are rolling back to a post-Release 5 sustaining patch, rather than to Release 5, reinstall the RPMs from that patch.)
rpm -Uvh --force [--prefix prefixValue] *.rpm
The --force option will allow the command to overwrite later packages of the same name. The --prefix option is not required unless the RPMs have been relocated. (If only a subset of the RPMs had been relocated, use individual file names as command arguments rather than *.rpm.)
- If you have converted data to the Release 5U1 format, restore the Release 5 data.
- Start Release 5 Java DB.
If you are using a network server, use the following command:
java -jar <JavaDB-base>/lib/derbynet.jar start
Otherwise, simply start any application using Java DB in embedded mode.
Multiple Instance Upgrades
In some deployment architectures Java DB is deployed on multiple computer systems to provide for scalability and to improve availability. For example, you might have Java DB instances running on multiple computers with a load balancer to distribute the load. In these architectures the registries are predominantly read-only and respond to a heavy query load by accessing a common database.
You perform the upgrade of Java DB on each computer as described in Release 5 Java DB Upgrade.
Upgrading Java DB from Java ES Release 4This section includes information about upgrading Java DB from Java ES 2005Q4 (Release 4) to Java ES 5 Update 1 (Release 5U1). The section covers the following topics:
Introduction
When upgrading Java ES Release 4 Java DB to Release 5U1, consider the following aspects of the upgrade process:
- General Upgrade Approach. The upgrade is achieved by performing a fresh install of Release 5U1 Java DB, replacing the Release 4 version. Release 4 configuration and data remain intact unless you explicitly convert data to a new format.
- Upgrade Dependencies. Java DB has a hard upgrade dependency on the J2SE shared component (see Table 1-10), which is automatically upgraded to Release 5U1 by the Java ES installer when you perform an upgrade of Java DB.
- Backward Compatibility. Release 5U1 Java DB is fully compatible with Release 4.
- Upgrade Rollback. A rollback of the Release 5U1 upgrade cannot be achieved except by reverting to a backed up Release 4 installation.
- Platform Issues. The general approach for upgrading Java DB is the same on both Solaris and Linux operating systems.
Release 4 Java DB Upgrade
This section describes how to perform an upgrade of Java DB from Java ES Release 4 to Release 5U1 on both the Solaris and Linux platform. The section covers the following topics:
Pre-Upgrade Tasks
Before you upgrade Java DB software you should perform the following tasks:
Verify Current Version Information
You can verify the current version of Java DB using the following command:
java -cp JavaDB-base/lib/derby.jar org.apache.derby.tools.sysinfo
See Table 8-4 for output values (for the version of the derby.jar file).
Upgrade Java DB Dependencies
It is generally recommended that all Java ES components on a computer system (and in a computing environment) be upgraded to Release 5U1. However, all shared components required by Java DB are upgraded automatically by the Java ES installer when you perform an upgrade of Java DB to Release 5U1.
Back Up Java DB Data
The Java DB upgrade from Release 4 to Release 5U1 does not modify configuration data, but might require conversion of persistent data to a new format. Therefore, it is recommended that you back up your entire Java DB installation and your data before upgrading Java DB. See Table 8-3.
Obtain Required Configuration Information and Passwords
No configuration information or password is required to upgrade Java DB.
Upgrading Release 4 Java DB
This section describes the upgrade procedure on Solaris and Linux platforms.
Upgrade Procedure
The procedure documented below applies to all Java DB instances residing locally on the computer where the upgrade is taking place.
- Log in as root or become superuser.
su -
- Stop Release 4 Java DB.
If you have a network server running, use the following command:
java -cp JavaDB-base/lib/derby.jar:JavaDB-base/lib/derbynet.jar org.apache.derby.drda.NetworkServerControl shutdown
Otherwise, simply shut down all applications using Java DB.
- Perform a fresh install of Release 5U1 Java DB.
Perform the following steps:
- Launch the Java ES installer on the computer hosting Release 4 Java DB.
cd Java ES Release 5U1 distribution/os_arch
./installerwhere os_arch matches your platform, such as Solaris_sparc. (Use the installer -nodisplay option for the command line interface.)
After the Welcome and License Agreement pages are displayed, you will be presented with a component selection page. (When installed components are detected that can be directly upgraded by the Java ES installer, they are shown with a status of "upgradable.")
- Select Java DB from the component selection page.
The previous installation will be overwritten.
- Select the Configure Later option.
Configure Now is not supported.
- If needed, select the option to install localized packages.
- Exit the Java ES installer when installation is complete.
- Apply the latest Java DB maintenance patches, if any.
- Check if there have been any Java DB point fixes subsequent to Release 5U1.
Periodically obtain the latest patches as described in Accessing Java ES Patches and compare them to the Release 5U1 patch revision numbers shown in Table 8-5 (Solaris) or Table 8-6 (Linux).
If you are using Sun Connection on the Solaris platform, you are automatically notified of new patches for Java ES components installed on your computer.
- Apply the appropriate Java DB core and, if needed, localization patches in that order.
On Solaris:
patchadd /workingDirectory/patch_IDIf you are using the accumulated patch cluster on the Solaris platform, the install_cluster script will apply any Java ES patches needed on your computer.
On Linux:
cd /workingDirectory/patch_ID
./installpatchBe sure to consult the README.patch_ID file for additional patch installation instructions.
- Confirm that the patch upgrades were successful:
On Solaris:
showrev -p | grep patch_IDOn Linux:
rpm -qa | grep sun-javadbThe output should return the appropriate patch IDs or version numbers.
- Start Release 5U1 Java DB.
If you are using a network server, use the following command:
java -jar <JavaDB-base>/lib/derbynet.jar start
Otherwise, simply start any application using Java DB in embedded mode.
Verifying the Upgrade
You can verify successful upgrade of Java DB using the following command:
java -cp JavaDB-base/lib/derby.jar org.apache.derby.tools.sysinfo
See Table 8-4 for output values (for the version of the derby.jar file).
Post-Upgrade Tasks
When upgrading Release 4 Java DB to Release 5U1, you must convert data from the Java DB 10.0 disk format to the 10.2 format if you want to take full advantage of the enhanced functionality of Release 5U1 Java DB.
To perform this conversion, connect to the database with upgrade=true appended to the JDBC URL. For example:
java -cp JavaDB-base/lib/derbytools.java:JavaDB-base/lib/derby.jar
org.apache.derby.tools.ijij version 10.2
ij> connect 'jdbc:derby:/databasePath;upgrade=true';
ij> exit;
For more information, see the Getting Started Guide in the docs directory of your Java DB installation.
Rolling Back the Upgrade
A rollback of the Release 5U1 upgrade cannot be achieved except by reverting to a backup Release 4 installation and its data.
Multiple Instance Upgrades
In some deployment architectures Java DB is deployed on multiple computer systems to provide for scalability and to improve availability. For example, you might have Java DB instances running on multiple computers with a load balancer to distribute the load. In these architectures the registries are predominantly read-only and respond to a heavy query load by accessing a common database.
You perform the upgrade of Java DB on each computer as described in Release 4 Java DB Upgrade.