Introduction
This article covers the main points you need to consider when migrating from JADE 6.3 to 7.0.
First off it’s important to establish that the conversion from JADE 6.3 to 7.0 is a migration and not an upgrade. This difference not seen with earlier JADE releases is necessary because of fundamental changes to the meta model for JADE 7.0. For example, the change to 64-Bit instance IDs, and the internal mechanisms used for collection structures.
To achieve these changes the source database is converted to 7.0 using JADE’s ConvertDb application. You may have used this yourself in the past to convert from ansi to unicode, or vice versa.
Note: Any environment which uses persistent DynaDictionaries must ensure that JADE hotfix 7.0.7.18 is installed before performing the migration. Refer to JADE Support Bulletin #24 for further information.Note: The JADE 6.3 to 7.0 migration process can not include an ansi to unicode conversion (or vice versa). Such a conversion can be made either prior to or post upgrade, but not during.
The migration can be performed in one of two ways: offline, and online (commonly known as ‘high availability’).
Migration Types
Offline
An offline migration is very similar to the process used in upgrading earlier releases of JADE to 6.3. The key difference is the source system is not itself converted to 7.0, but instead the 7.0 system is created from it. During this process the system is unavailable to users.
It consists of the following steps:
- The production 6.3 system is shut down.
- The 6.3 system is used to seed the creation of a 7.0 database.
- The standard 6.3 to 7.0 upgrade reorg and validation scripts are executed on the 7.0 database.
- All SDS/RPS secondaries are recreated from the 7.0 database.
- The 7.0 database is brought online as the new production system.
High AvailabilityNote: you can use the InstallShield installer to perform an offline migration.
The high availability option is slightly more complex than the offline option, but means the source system remains online (allowing persistent updates to occur) while the migration process is underway. It only needs to go offline for a relatively short time in order to perform the last few steps of the process.
It consists of two phases:
Phase 1:
- A backup of the 6.3 system is taken for conversion to the 7.0 format.
- The source 6.3 system continues to process update transactions.
- The 6.3 system’s backup is used to seed the creation of a 7.0 database.
- All completed journals since the backup was taken are applied to the converted 7.0 database.
Phase 2:
- The production 6.3 system is shut down.
- Any remaining 6.3 journals are applied to the converted 7.0 database.
- The standard 6.3 to 7.0 upgrade reorg and release scripts are executed on the 7.0 database.
- All SDS/RPS secondaries are recreated from the 7.0 database.
- The 7.0 database is brought online as the new production system.
Please note though, structural changes to the still-running 6.3 database are not permitted as they would invalidate the new 7.0 database.
Attached to this article are the following files: ReadmeInstallSteps.doc and HighAvailabilityUpgradeSteps.doc.
They document the steps necessary to complete both the offline and high availability migrations respectively.
Pre Migration Requirements
Database Certification
Certification of the source database must occur before migration to 7.0 is undertaken.
Because the migration utilises the JADE ConvertDb application which reads all persistent data and writes (after converting it) to a new database you need to have confidence that it won’t fail due to certification errors within the source system. These could be of three types, i.e. physical errors, meta logical errors and user logical errors.
- Physical errors are logged when structural corruption is detected in system or user .dat files. It’s possible for structural corruption to exist and not be noticed at runtime (e.g. in seldom used classes, or class instances), however such errors would pose a problem to the migration process.
- Meta logical errors are errors in the meta data that defines your object model. These are internal to JADE. The analysis and repair of these is also covered in Source Bulletin #4.
- Logical errors refer to referential integrity errors in the user data, e.g. object A has a reference to object B, but object B’s inverse back is null, the relationship is only known about from one side. (Source Bulletin #4 "Database Logical Integrity Analysis and Repair" covers finding and fixing such errors in detail, https://forums.jadeworld.com/viewtopic.php?f=24&t=1657.)
We have had reports of the certification process taking a significant amount of time in some environments. The certification process is I/O intensive, so if certification times are important to you we suggest running these operations on a host with a high performance IO subsystem. For example one with fast locally attached disk, potentially even solid state disk. Further hints are in Source Bulletin #19 "JADE Logical Certify Performance Hints and Tips" (https://forums.jadeworld.com/viewtopic.php?f=24&t=1866)
Space Requirements
The two migration types require different amounts of disk, as shown below:
Offline:
- Space for the target 7.0 database, allowing for natural size increase of the database (see Database Size Increase section).
High Availability :
- Space for an online backup of the 6.3 database.
- Space for the restored backup, used to seed the 7.0 system.
- Space for the target 7.0 database, allowing for natural size increase of the database (see Database Size Increase section).
- Space for the recovery journals produced both on the source 6.3 system and copied to the new 7.0 system.
Database Size Increase
All databases will vary in size when converted to JADE 7.0. Most will increase, the odd one (observed) might decrease in size. The increase is explained by the move to use eight byte (64-Bit) instance IDs instead of four byte (32-Bit) IDs.
What this means is, for every object in your database, as well as internal meta objects, references, object properties, methods, etc (anything with an OID) will all grow by four bytes.
The following table shows results of database migrations performed by Jade Support:
Looking at the results in the above table it’s important to consider the following; smaller systems (e.g. development, test) may have a larger overall size increase than medium or large systems. This is because the proportion of meta data to user data is likely to be higher in smaller systems. Therefore when the instance IDs of those meta data objects are doubled in size the objects overall size increase is in a sense distorted due to the large percentage of meta-data. ‘Real world’ systems that consist of real user data, with volume, will see a smaller overall size increase.Note: All figures for Collection Reblocking were taken after the 7.0 database was compacted.
For more information on the Collection Reblocking process see the Post Migration section towards the end of this document.
Disk Cache Settings
During the convert DB stage there can be a memory allocation conflict between the Windows File System cache underlying the JADE 6.3 Database read activity and the JADE 7 Disk Cache.
This can lead to poor performance and in certain configurations can cause the conversion to fail before completing. To alleviate the symptoms here, it is recommended that during the upgrade process allocate the memory upfront by setting the DiskCacheMaxSegments and DiskCacheMinSegments to the same value.
On systems which meet or exceed the minimum specification the recommended value equates to 1GB. This is 16 Segments if you have left your other Disk Cache settings at their default values.
The recommended approach is to add the following to the jdbupgrade.exe command line referenced in the instructions provided in ReadmeInstallSteps.doc and HighAvailabilityUpgradeSteps.doc:
Code: Select all
PersistentDb.DiskCacheMaxSegments=16 PersistentDb.DiskCacheMinSegments=16If you do set these values in the Initilisation file, then once the migration is complete this disk cache limitation should be removed, or increased to a more appropriate value. The performance of the JADE 7 system will be severely limited, if these recommended settings are left in place.
Further information on DiskCache is available in the documentation, particularly the initialisation file reference and the JADE 7 release notes.
Migration
When you are confident the source system is free of certify errors (see prior section) it’s now ready for migration to 7.0.
It’s important to note the time taken to migrate systems is very dependent on the host environment’s hardware and resource availability. e.g. VM machines with SAN disks may suffer from contention issues not seen on a dedicated server.
To aid you with getting the best performance out of the host the migration (ConvertDb phase) can be multithreaded. This is done by specifying the ‘copies=’ parameter when performing the ConvertDb phase of the migration.
The number of workers can be tuned to best suit the environment’s IO/CPU capabilities. For example, setting copies to 4 on a dual core machine would be redundant as you now have four threads fighting for contention over two CPU cores. A good rule of thumb (on a machine where the application has exclusive access to the CPU) is to set the workers = (CPU cores - 1)
If you’ve previously tuned the number of reorg workers for the database, this is likely to be a good starting point for setting the number of workers used in the ConvertDb phase.Note: The term ‘cores’ refers to both physical and logical cores, e.g. those that support hyperthreading.
Duration of Migration
While a commonly asked question, it’s a metric that is really only relevant to the system from which it came. This is because of the factors involved, e.g. number of objects, number of internal object references, size of those objects, hardware capabilities (CPU, IO and RAM). All of these contribute to the speed of the migration.
The following try to give an indication of expected durations.
Offline:
A good starting point is to plan for the migration to take about as long as a full database reorganisation.
Online (High Availability):
The first phase, converting the database, is the same as the offline migration type; plan for this to take about as long as a full database reorganisation (remembering that the system can continue to be used during this time).
The second phase, which must occur offline does not take so long and is designed to minimise the system’s unavailability. It takes as long as the time required to replay any outstanding journals produced during phase one, and complete the two internal reorgs and run the upgrade release scripts. The running of upgrade scripts usually less than a couple of minutes.
Post Migration
Reblocking Collections
JADE collections are composite objects comprised of a collection header and one or more collection blocks that may vary in size. For all collection types, the first block is instantiated with a size sufficient to contain exactly four entries. As entries are added to the collection, the collection block grows in increments up to a system determined size limit. This size limit can be influenced by user specified tuning parameters: “Entries Per Block” or “Expected Population”.
In JADE 7, database files are organized as a sequence of 8K byte disk blocks, which is the basic unit of I/O and free-space management. As a consequence of this, the rules for determining the default maximum size for collection blocks have been changed to provide better alignment with the new database block structure.
When a 6.3 database is migrated to the new JADE 7 structure, collection blocks are not restructured to conform to the new alignment rules. This may result in sub-optimal space utilisation or performance characteristics in some cases.
For more information on this subject please see Source Bulletin #18, “Reblocking Collections in JADE 7.0”, found here: https://forums.jadeworld.com/viewtopic.php?f=24&t=1837.
This reblocking is deliberately not included in the migration process as it may consume a considerable amount of time and can be performed later, outside the outage window if necessary.
Note: The collection reblocking and subsequent compaction routines can occur while the database is online.