B
Migration and Compatibility

This appendix explains the steps that need to be taken to migrate a replication environment from Oracle7 to Oracle8. Topics covered include:

• Migration Overview
• Migration of Master Sites
• Migration of Snapshot Sites
• Upgrading to Primary Key Snapshots
• Features Requiring Migration to Oracle8
• Obsolete procedures

Migration Overview

An existing Oracle7 replication environment can be migrated to Oracle8 incrementally. Oracle7 sites can coexist with Oracle8 sites in the same replication environment to allow for replication and administrative operations to be run successfully.

In some cases you may find it easier to migrate your environment, particularly the multimaster component of your environment, in one step. Typically, this will only be possible for small configurations.

If you will be migrating your Oracle7 replication environment incrementally, you must first upgrade all snapshot sites to Oracle7 Release 7.3.4 or greater to allow replication between the Oracle7 snapshot sites and Oracle8 master sites. If you will be migrating your Oracle7 master sites incrementally, you must first upgrade all master sites to Oracle7 Release 7.3.3 or greater to allow replication between the Oracle7 and Oracle8 master sites.

If you are migrating incrementally, master sites should be migrated first. When this has been completed you can migrate the snapshot sites to Oracle8.

When a master site is migrated to Oracle8 all snapshots at all of the master's Oracle7 or Oracle8 snapshot sites must be full refreshed.

Once a site has been migrated, downgrading from Oracle8 to Oracle7 is not supported.

Certain Oracle8 replication features require that all sites be successfully migrated to Oracle8 before the features can be used. For example, both a snapshot's site and the snapshot master's site must be migrated to Oracle8 to use primary key snapshots. The Oracle8 simple snapshots with subqueries feature and the master table reorganization procedures require that you first upgrade from Rowid snapshots to primary key snapshots.

Migration using a full database export from Oracle7 and import to Oracle8 is also supported.

Migration of Master Sites

Master sites can be migrated either incrementally or all at one time. Incremental migration requires that all master Oracle7 sites be first configured with appropriate administrative accounts and links to ensure compatibility with the Oracle8 security model. Incremental migration therefore is more complex but will typically be necessary if you have a large multimaster configuration.

Migration of All Master Sites at One Time

To migrate all of your Oracle7 master sites at one time, you must first upgrade any snapshot sites that will remain on Oracle7 to Oracle7 Release 7.3.4 or greater to enable the snapshot sites to replicate with the Oracle8 masters, then follow these steps:

1. Quiesce the replication environment by executing DBMS_REPCAT. SUSPEND_MASTER_ACTIVITY at the master definition site for all master replication groups, and stopping all propagation and refreshing from snapshot sites to the master, e.g., by temporarily suspending or "breaking" entries in the job queue that control automated propagation and refreshing at the snapshot sites. You must also resolve and re-execute any errors in the local error queue until it is empty.
   
   For more information see the following sections in Oracle 7 Server Distributed Systems, Volume II: Replicated Data: Chapter 4 - "Asynchronous Propagation of DML Changes", and "Suspending Replication Activity", as well as Chapter 7 - "Resolving an Error Manually".
2. Migrate all master sites using the Oracle7 to Oracle8 Migration Utility and replication CATREP8M.SQL script as documented in Oracle8 Server Migration.
3. Using the Replication Manager setup wizard, create a primary master replication administrator account granting this user Oracle8 Replication Administrator, Propagator, and Receiver privileges on all master sites, and set up the appropriate links connecting all sites. See "Preparing for Multimaster Replication" on page 3-4.
4. Using Replication Manager or the replication management API, regenerate replication support for each replication base object. See "Generating Replication Support for Master Group Objects" on page 3-28 for more information. Among other activities, generating replication support will establish the registered propagator as the owner of generated objects
5. Using Replication Manager or the replication manager API, resume replication activity by unquiescing the environment. See "Resuming Replication Activity for a Master Group" on page 3-20 for more information.
6. All snapshots at all snapshot sites will need a full refresh after their master sites have been migrated to Oracle8. Because of the new Oracle8 rowid format, the Oracle7 to Oracle8 migration utility truncates all master snapshot logs. If you used the DBMS_JOB.BROKEN procedure to help isolate you master site in Step 3, "unbreak" your jobs to resume your replication activity from your snapshot sites.
   
   If your snapshots have been defined with the refresh "FORCE" option, their next attempted refresh will full refresh automatically. Snapshots defined with the refresh "FAST" option will need to be manually refreshed using dbms_refresh.refresh or other refresh procedures.
   

If you are using procedural replication at snapshot sites, also regenerate snapshot support on all packages and package bodies used for procedural replicaton.

Note: If you are able to migrate all of the master's snapshot sites to Oracle8 when the master site is migrated to Oracle8, i.e., you do not need to migrate the snapshot sites incrementally, you can alternatively drop the snapshot logs for the master and recreate them as primary key snapshot logs. The snapshots at each snapshot site should be altered to convert them to primary key snapshots. You can then do a full refresh for each primary key snapshot. See Upgrading to Primary Key Snapshots on B-11" for additional details.

1. Drop any administrative accounts and links that you were using to maintain your Oracle7 multimaster replication environment that are not needed in your Oracle8 environment. Unnecessary privileges may also be revoked. Be careful not to drop accounts that are needed to maintain any snapshot sites.

Incremental Migration of Master Sites

To incrementally migrate your Oracle7 Release 7.3.3 or greater master sites to Oracle8, you must first upgrade any snapshot sites that will remain on Oracle7 to Oracle7 Release 7.3.4 or greater to enable the snapshot sites to replicate with the Oracle8 masters. The next step is to prepare all Oracle7 master sites by configuring them with the appropriate administrative accounts and links to ensure compatibility with the Oracle8 security model.

Preparing Oracle7 Master Sites for Incremental Migration

Oracle7 master sites must be first be configured so that all replication administrative functions and propagation can be done within the security context of a single administrative user at each site. The primary master replication administrator must be created as the same user at all Oracle7 and Oracle8 sites when the compatibility conversion and Oracle8 migration are complete. Your Oracle7 master sites may already be configured in this manner. If not, leave your current configuration as it is and follow these additional steps:

1. Select the primary master replication administrator for the incrementally migrated environment. You may select your current replication administrator or create a new user.
2. At each master site grant the required privileges to the primary master replication administrator using both DBMS_REPCAT_ADMIN.GRANT_ADMIN_ANY_REPGROUP and DBMS_REPCAT_AUTH.GRANT_SURROGATE_REPCAT.
3. Create or confirm the following database links at each master site:
   • Login as the SYS user, then create or confirm public database links that connect to each of the master sites being configured for Oracle8 compatibility, using a valid global database name and SQL*Net 2.3 TNS alias.
   • As the SYS user, create or confirm private database links to each of the master sites being configured for Oracle8 compatibility by connecting as the primary master replication administrator, referencing the public database link, and supplying the connect information for the primary master replication administrator.
   • Login as the primary master replication administrator and create or confirm private database links that connect to the master sites. The links need to reference the public database link and supply the connect information for the primary master replication administrator.

Incremental Migration Steps

Now that your Oracle7 multimaster configuration is prepared, you can incrementally migrate each master site to Oracle8 following these steps:

1. Pick a master site to migrate. You should migrate your master definition site(s) first.
2. If you are using procedural replication, record the configuration information and locations (schemas) of existing procedure wrappers. This information will be used later.
3. Isolate the master site from the replication environment. This can be done by either:
   • Quiescing the replication environment by executing DBMS_ REPCAT.SUSPEND_MASTER_ACTIVITY at the master definition site for all master replication groups, and stopping all propagation and refreshing from snapshot sites to the master, e.g., by temporarily suspending or "breaking" entries in the job queue that control automated propagation and refreshing at the snapshot sites. You must also resolve and re-execute any errors in the local error queue until it is empty, or
   • Stopping all propagation to the site from other master and snapshot sites, e.g., by executing DBMS_DEFER_SYS.UNSCHEDULE_ EXECUTION (at Oracle7 sites) or "DBMS_DEFER_SYS.UNSCHEDULE_PUSH" on page 10-39 (at Oracle8 sites) on the remote sites and stopping all local updates to replicated data on the master and temporarily suspending or "breaking" entries in the job queue that control automated propagation and refreshing at the snapshot sites. Empty the local deferred transaction queue by manually pushing the queue to all sites. Resolve and re-execute any errors in the local error queue until empty. Refrain from executing any administrative operations at the master definition site that may impact the master site being migrated.
     
     For more information on completing the tasks in Step 1, see the following sections in Oracle 7 Server Distributed Systems, Volume II: Replicated Data: Chapter 4 - "Asynchronous Propagation of DML Changes", "Suspending Replication Activity", "Removing a Master Site from the Deferred Push List", and "Forcing the Deferred Transaction Queue to Push", as well as Chapter 7 - "Resolving an Error Manually" .
4. Migrate the master site using the Oracle7 to Oracle8 Migration Utility and replication CATREP8M.SQL script as documented in Oracle8 Server Migration.
5. Using the Replication Manager setup wizard or the replication management API, grant your primary master replication administrator Oracle8 Primary Replication Administrator, Propagator, and Receiver privileges for the master site. See "Preparing for Multimaster Replication" on page 3-4 for more information. Database links from the schema of the primary replication administrator to connect to all other Oracle7 and Oracle8 masters as the primary master replication administrator should already exist if you prepared your Oracle 7 master site for compatibility with Oracle8 using the directions above.
6. If you are not already in a quiesced state, use Replication Manager or the replication management API to suspend all replication activity for all master groups. See "Suspending Replication Activity for a Master Group" on page 3-18 for more information.
7. Using Replication Manager or the replication management API, regenerate replication support for each replication base object. See"Generating Replication Support for Master Group Objects" on page 3-28 for more information. If any sites in the replication environment are still running Oracle7, you must set the "min_communication" parameter to FALSE. The "min_communication" parameter should only be set to TRUE (the default) once all sites have been migrated to Oracle8. See "Minimizing Data Propagation" on page 7-30. Among other activities, generating replication support will establish the registered propagator as the owner of generated objects
8. If you are using procedural replication, check your remaining Oracle7 master sites to determine whether the wrappers have been moved (list created from Step 2). If they have been moved, create a synonym in their old location (in the schema of either the replication administrator or the table owner, depending on whether the site previously used the system-based or user-based model) pointing to the new location in the schema of the primary replication administrator. Confirm necessary object privileges have been granted to access the new owner and locations. If you are also using procedural replication at snapshot sites, regenerate snapshot support on all packages and package bodies used for procedural replicaton.
9. Using Replication Manager or the replication management API, resume replication activity and unquiesce the environment for each master group. See "Resuming Replication Activity for a Master Group" on page 3-20 for more information. If you have isolated the master by unscheduling propagation to other masters and from other masters then reschedule propagation by executing DBMS_DEFER_SYS.SCHEDULE_EXECUTION (at Oracle7 sites) or "Editing a Scheduled Link" on page 3-12(at Oracle8 sites) for all master sites.
10. All snapshots at both Oracle7 and Oracle8 snapshot sites will need a full refresh after their master site has been migrated to Oracle8. Because of the new Oracle8 rowid format, the Oracle7 to Oracle8 migration utility truncates all master snapshot logs. If you used the DBMS_JOB.BROKEN procedure to help isolate you master site in Step 3, "unbreak" your jobs to resume your replication activity from your snapshot sites.
    
    If your snapshots have been defined with the refresh "FORCE" option, their next attempted refresh will full refresh automatically. Snapshots defined with the refresh "FAST" option will need to be manually refreshed using dbms_refresh.refresh or other refresh procedures.
    
    Note: If you are able to migrate all of the master's snapshot sites to Oracle8 when the master site is migrated to Oracle8, i.e., you do not need to migrate the snapshot sites incrementally, you can alternatively drop the snapshot logs for the master and recreate them as primary key snapshot logs. The snapshots at each snapshot site should be altered to convert them to primary key snapshots. You can then do a full refresh for each primary key snapshot. See Upgrading to Primary Key Snapshots on B-11" for additional details.
11. Drop any administrative accounts and links that you were using to maintain your Oracle7 multimaster replication environment that are not needed in your Oracle8 environment. Unnecessary privileges may also be revoked. Be careful not to drop accounts that are needed to maintain any snapshot sites or Oracle7 master sites. .

Migration of Snapshot Sites

Assuming that the snapshot's master site have been migrated to Oracle8, you can migrate an Oracle7 Release 7.3.4 or greater snapshot site to Oracle8 by following these steps. If the master site has not been migrated to Oracle8, follow the instructions in ""Migration of Master Sites" on page -3" before proceeding.

1. Isolate the snapshot site from the replication environment by stopping all local updates to updatable snapshots at the snapshot site (in a separate session you may lock each snapshot's base table to prevent further transactions). Empty the local deferred transaction queue by pushing the queue to the snapshot's master. Reference the Oracle 7 Server Distributed Systems, Volume II: Replicated Data Chapter 4, "Asynchronous Propagation of DML Changes" for more information. Stop all propagation from the snapshot site to its master, e.g., by temporarily suspending or "breaking" entries in the job queue that control automated propagation and refreshing at the snapshot sites.
2. Run the Oracle7 to Oracle8 Migration Utility and replication CATREP8M.SQL script as documented in Oracle8 Server Migration.
3. Use the Replication Manager setup wizard or execute the appropriate replication management API calls to configure the primary snapshot replication administrator user as the replication administrator and propagator for the snapshot site, a receiver account at the master, and the appropriate links to the master.
4. Using Replication Manager or the appropriate replication manager API calls, regenerate snapshot replication support. See "Regenerating Replication Support for an Updatable Snapshot" on page 4-22 for more information. Among other activities, generating replication support will establish the registered propagator as the owner of generated objects
5. Using Replication Manager or the appropriate replication manager API calls, reschedule propagation and/or refresh intervals with the master and enable local updates where appropriate. If you used the DBMS_JOB.BROKEN procedure to help isolate you master site in Step 1, you make need to "unbreak" your jobs to resume your replication activity from your snapshot sites.
6. Drop any administrative accounts and links that you were using to maintain your Oracle7 replication environment that are not needed in your Oracle8 environment. Unnecessary privileges may also be revoked.

Migration Using Export/ Import

Full database export from Oracle7 Release 7.3.3 or greater and import to Oracle8 is supported for both masters and snapshots. You may use export/import as an alternative to the Oracle7 to Oracle8 Migration Utility and replication CATREP8M.SQL script in the procedures described above. Be sure that you follow all the steps, both before and after the actual migration from Oracle7 to Oracle8, in the above procedures however.

To export a full database from Oracle7 Release 7.3.3 or greater and import to Oracle8, follow these steps:

1. Export the Oracle7 Release 7.3.3 or greater database to a dump file using the Release 7.3 export utility under the system schema with FULL=y.
2. Startup an Oracle8 database with advanced replication installed. Connect as SYSTEM and execute dbms_repcat_mig.pre_import. This procedure temporarily disables referential constraints on the replication data dictionary tables.
3. Import the dump file to the Oracle8 database using the Oracle8 import utility under the system schema with FULL=y. The referential constraints on the replication data dictionary tables will be automatically enabled.

You may also export data from individual Oracle7 tables, import the data to Oracle8 tables, and then configure those tables as masters in an Oracle8 replication environment using standard advanced replication procedures.

See the Oracle8 Server Utilities reference guide for more information.

Upgrading to Primary Key Snapshots

Once a snapshot site and its master have been migrated to Oracle8, you can upgrade your rowid snapshots to Oracle8 primary key snapshots. To do this you must first alter the snapshot logs for each master table to log primary key information, as well as rowid information, when master rows are updated. Once this is completed at your master site(s), you can incrementally convert your Oracle8 snapshots sites by altering the snapshots to convert them to primary key snapshots. Oracle8 masters that have been altered to log primary key as well as rowid information can support Oracle7 rowid snapshots as well as Oracle8 rowid and primary key snapshots simultaneously to allow for incremental migration.

Note: A primary key snapshot cannot be converted or downgraded to rowid snapshots.

Primary Key Snapshots Conversion at Master Site(s)

To support primary key snapshots, do the following at the Oracle8 master site:

1. Define and enable a primary key constraint on each master table that does not already have a primary key constraint enabled.
2. Alter the snapshot log for each master table supporting fast refresh to include primary key information using the ALTER SNAPSHOT LOG command. See ALTER SNAPSHOT LOG in the Oracle8 Server SQL Reference manual for additional information.

Note: If the above conditions are not met an error will be raised when you execute the ALTER SNAPSHOT command at the snapshot sites to convert to primary key snapshots.

Primary Key Snapshot Conversion at Snapshot Site(s)

After the Oracle8 master site has been configured to support primary key snapshots, do the following at the Oracle8 snapshot sites:

1. Isolate the snapshot site from the replication environment by stopping all local updates to updatable snapshots at the snapshot site.
2. If any read-only ROWID snapshots being converted to primary key snapshots do not include all the columns of the primary key, drop and recreate them with all the primary key columns. See "Creating Simple Snapshots" on page 2-11 for more information.

Note: Constraints should not be defined on Rowid snapshots.

1. Perform a fast refresh of all snapshots to remove the need for any remaining rowid references in the master snapshot log.
2. Use the ALTER SNAPSHOT command to convert rowid snapshots to primary key snapshots. For complete syntax information, see Oracle8 Server SQL Reference.
3. Resume replication by rescheduling propagation and/or snapshot refresh with the master, enabling local updates where appropriate. If you used the DBMS_JOB.BROKEN procedure to help isolate you master site in step 1, you make need to "unbreak" your jobs to resume your replication activity from your snapshot sites.

Features Requiring Migration to Oracle8

The following features require that all the sites involved be successfully migrated to Oracle8:

1. Replication of LOB data types
2. Reduced data propagation
   • min_communication parameter and
   • send_and_compare_old_values procedure
3. Parallel propagation of deferred transactions
4. Global authentication and privileged database links
5. Validate procedure

Additional Information: See ... (Appendix A).

The following features require that all the sites involved must be successfully migrated to Oracle8 and primary key snapshots:

1. Simple snapshots with subqueries
2. Master table reorganization procedures

The following features will automatically work in mixed Oracle7 and Oracle8 environments, but only impact Oracle8 sites:

1. Fine grained quiesce
2. Snapshot registration

Note: All master groups at Oracle7 sites will be quiesced if any master group at that site is quiesced.

Note: Oracle7 snapshots will not be automatically registered at Oracle8 sites but can be manually registered using the DBMS_SNAPSHOT.REGISTER_ SNAPSHOT and DBMS_SNAPSHOT.UNREGISTER_SNAPSHOT procedures at the master site(s). See "Registering a Snapshot at its Master Site" on page 2-35 for more information

Obsolete procedures

Procedures that are obsoleted in Oracle8 include:

DBMS_REPCAT_ADMIN.GRANT_ADMIN_REPGROUP

DBMS_REPCAT_ADMIN.GRANT_ADMIN_ANY_REPGROUP

DBMS_REPCAT_ADMIN.REVOKE_ADMIN_REPGROUP

DBMS_REPCAT_ADMIN.REVOKE_ADMIN_ANY_REPGROUP

DBMS_REPCAT_AUTH.GRANT_SURROGATE_REPCAT

DBMS_REPCAT_AUTH.REVOKE_SURROGATE_REPCAT

DBMS_DEFER_SYS.EXECUTE

---