Administration Tools - ooupgrade

Printer-friendly version
Upgrades a database or a federated database to match a new Objectivity/DB release.
-systemdbonly | -db dbSysName | -id dbId | -all
[-pagesize size]
[-format newArch]
[-force] [-licensefile fileName]
[-schemalock lockVal]
Upgrades just the system database.
-db dbSysName
Upgrades an individual database specified by system name. If the system database has not yet been upgraded, it is automatically upgraded first.
-id dbId
Upgrades an individual database specified by integer identifier (for example, 78). This option also accepts the identifier specified in D-C-P-S format (for example, 78-0-0-0). If the system database has not yet been upgraded, it is automatically upgraded first.
Upgrades the entire federated database, including the system database and every database.
-pagesize size
Storage-page size, in bytes, for each database being upgraded. Allowable page sizes are integer multiples of 8 between the database’s original page size and 65536 (inclusive). If you omit this option, the database’s original storage-page size is used.
If you are upgrading multiple databases, the specified page size applies to all of them. The specified page size must be greater than or equal to the largest page size used by these databases.
-format newArch
New owning architecture for the storage pages in each database being upgraded, including the system database. This architecture defines the disk format that will be used by these pages after upgrading. If you omit this option, the original format of the storage pages is retained (except in the case of the system database, which assumes the format of the current host machine).
The newArch value must be an architecture name recognized by Objectivity/DB. For a list of the recognized architectures, run this tool with the -help option. Note:
The recognized names for supported Windows architectures are win32 and win64.
The recognized names for the supported UNIX architectures are listed in the Objectivity/DB installation chapter of Installation and Platform Notes for UNIX. (The name for a UNIX architecture is the arch component of the Objectivity/DB installation-directory path installDir/arch on a UNIX workstation.)
Note: When converting from a 32-bit to a 64-bit architecture, some basic objects might no longer fit in their original storage space due to an increase in the class’s size. Such an object is automatically moved to a page with more space, and a link to its new location is maintained by a redirection stub left in the original location. To avoid this redirection, you can adjust the storage page size; see the discussion below.
Performs the requested upgrade even if the specified databases already use the Release 9.0 (or later) format. This is useful if you want to change the storage-page size on a new or previously upgraded database.
-licensefile fileName
File containing the license for the upgraded federated database. You may optionally include a path to the directory containing the file; if you specify a filename without a path, the file must reside in the current directory.
If you omit this option, ooupgrade uses the default license file oolicense.txt in the directory implied by bootFilePath. If no default license file is found there, ooupgrade looks for it in the following location:
(Windows) Objectivity/DB installation directory installDir
(UNIX) Your home directory; otherwise, the Objectivity/DB installation directory installDir
An error is reported and ooupgrade terminates if no license file is found.
-schemalock lockVal
64-bit unsigned integer key for unlocking the schema for this upgrade operation. You can normally omit this option because, by default, the schema is not locked. This option is required only if you have explicitly locked the schema of a federated database using Objectivity/DB Active Schema.
Nonconcurrent mode. Use this option only if the lock server for the specified federated database or autonomous partition is stopped. If the lock server is running, the tool reports an error and terminates.
Suppresses the copyright notice and program title banner. Useful when invoking the tool from another tool or product.
Suppresses all normal program output.
Prints the tool syntax and definition to the screen.
Path to the boot file of the federated database to be upgraded. You can omit this argument if you set the OO_FD_BOOT environment variable to the correct path. (HA) You can specify the boot file of any autonomous partition.
This tool changes the internal database format of a pre-Release 9.0 database or federated database to Release 9.0 (or later); see the Objectivity Release Notes. All objects in the upgraded databases keep their original object identifiers.
Warning: An upgraded federated database cannot be accessed by pre-Release 9.0 tools and applications. Do not perform an upgrade if interoperating with such tools and applications is required.
Warning: Always make a full backup of your federated database before you perform an upgrade. If you are upgrading a series of individual databases, the safest procedure is to make a full backup before you upgrade each database. Consult the Objectivity Customer Support Web site for more information on backup strategies.
This tool enables you to choose whether to upgrade an entire federated database or one database at a time. To upgrade a federated database, use the -all option. To upgrade an individual database, use the -db or -id option. If you upgrade an individual database and the system database has not been upgraded, it will automatically be upgraded first. If you want to upgrade only the system database, use the -systemdbonly option.
The ooupgrade tool obtains an exclusive lock on the database being upgraded. While the system database is being upgraded, no other concurrent applications can access the federated database. However, once the system database is upgraded, concurrent access can be resumed in databases other than the database being upgraded. If other concurrent applications are accessing the database before the upgrade, ooupgrade will quit with an error.
Before attempting to upgrade a federated database or database, you should verify that it is free of consistency errors (use the oocheck tool). You will need to fix any inconsistencies before upgrading. For example, you could use the oofix tool or call Objectivity Customer Support.
Before ooupgrade can upgrade the system database of a federated database, you must ensure that the federated database has a current license. However, for security reasons, the ooupgrade tool does not transfer the license data when it creates the upgraded version of the system database. Consequently, ooupgrade must be able to access your current Objectivity license file. The ooupgrade tool will automatically look for a default license file; if, however, you maintain your license file with a nondefault name or location, you must specify your license with -licensefile.
Each database is upgraded “in place.” The original database is renamed with a tilde appended to the original filename. A database with the new format is created using the original filename, and is then populated with the information from the original database. The renamed original database is deleted, leaving the now-upgraded database with the original filename.
Consequently, this tool requires the temporary free space equivalent to the size of the original database. If more than one database is being upgraded, the free space must be equal to the size of the largest database to be upgraded. (You will need even more free space if you are increasing the storage-page size of your database or converting from a a 32-bit to a 64-bit format.) The new database is always created in the same directory as the original database.
The upgrade of the system database is handled somewhat differently than an application-specific database. The information stored in the original system database is exported into a temporary XML file. The new system database is then populated with the information from the XML file.The temporary XML file is deleted as is the renamed original system database.
If you are upgrading multiple databases and ooupgrade terminates before the upgrade is complete, any completed databases remain upgraded. If a database was being upgraded at the time of the termination, you must restore it from the most recent backup. Alternatively, you might be able to use the renamed original database (with the tilde at the beginning of its name).
By default, the storage pages of an upgraded database continue to be owned by their original architecture (except in the case of the system database, which assumes the format of the current host machine). You can specify a different architecture using -format, which affects all databases (including the system database).
By default, this tool preserves each database’s original storage-page size. You can change the page size with -pagesize, but if you are upgrading multiple databases, they will all have the same storage-page size. This option can only be used to increase page sizes.
If the storage pages of the database are owned by a 32-bit architecture and the upgrade operation will cause them to be owned by a 64-bit architecture, the upgrade process automatically performs redirection as needed to account for larger sized basic objects.
Redirection can have a very minor performance impact for operations that access persistent objects. If you want to avoid redirection during an upgrade, specify a larger page size for the upgrade. One conservative approach is to use one and one half times the current page size, if this is possible without exceeding the maximum possible page size.
If the database contains any basic object that was redirected as a result of schema evolution, this redirection is preserved.
The ooupgrade tool will skip a database with no action if the database already has the Release 9.0 (or later) internal database format. If you want ooupgrade to change the disk format or page size of such a database, you must specify -force.
After the upgrade, any backup set entries and information about previous backups are lost. Accordingly, the first backup after an upgrade should be a full backup.
(HA) To upgrade the system database, ooupgrade requires all autonomous partitions to be accessible. To upgrade an individual replicated database, it is sufficient for the partitions controlling the database’s images to be accessible.

Tuesday, October 30, 2012