B
Migration and Compatibility

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

• Migration Overview.

• Migrating All Sites at Once.

• Incremental Migration.

• Upgrading to Primary Key Snapshots.

• Features Requiring Migration to Oracle8/Oracle8i.

• Obsolete procedures.

• Note: This appendix addresses the need to migrate from Oracle7 to Oracle8i. For more information about migrating from Oracle8 to Oracle8i, please refer to the Oracle8i Migration manual.

Migration Overview

In some cases you may find it easiest to migrate your environment, particularly the multimaster component of your environment, in one step. Typically, this will only be possible for small configurations. Instead, you may wish to migrate an existing Oracle7 replication environment to Oracle8i incrementally. Replication and administrative operations can be run successfully in a mixed Oracle7 and Oracle8i replication environment.

To successfully interoperate, however, you must observe the following restrictions:

• Oracle8i snapshot sites can only interact with Oracle7 Release 7.3.3 or greater master sites.

• Oracle8i master sites can only interact with Oracle7 Release 7.3.4 or greater snapshot sites and with Oracle7 Release 7.3.3 or greater master sites.

After migrating a master site to Oracle8i, perform a full refresh of all of associated snapshot sites.

Downgrading from Oracle8i to Oracle7 is not supported.

Certain Oracle8i replication features require that all sites be successfully migrated to at least Oracle8 before the features can be used. For example, before you can use primary key snapshots, both the snapshot site and its associated master site must be migrated to at least Oracle8. The Oracle8i 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 Oracle8i is also supported.

Migrating All Sites at Once

This section describes how to migrate your entire multimaster environment at once to Oracle8i. Note that any snapshot sites that you do not also migrate to Oracle8i, must be upgraded to Oracle7 Release 7.3.4 or greater.

Follow these steps to migrate all master sites and (optionally) snapshot sites at one time:

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, for example, 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 Oracle8i Migration Utility and by executing the appropriate migration scripts as documented in Oracle8i Migration (e.g. CATREP.SQL and ROLD_RELEASE.SQL, where old_release is the previously installed release).

3. Using the Replication Manager setup wizard, create a primary master replication administrator account granting this user Oracle8i Replication Administrator, Propagator, and Receiver privileges on all master sites, and set up the appropriate links connecting all sites. See "Preparing for Multimaster Replication".

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" 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 management API, resume replication activity by unquiescing the environment. See "Resuming Replication Activity for a Master Group" for more information.

6. At a minimum, you must now upgrade all associated snapshot sites to Oracle7 Release 7.3.4. For instructions on migrating your snapshot sites to Oracle8i, see "Incremental Migration of Snapshot Sites".

7. All snapshots at all snapshot sites will need a full refresh after their master sites have been migrated to Oracle8i. Before the refresh, be certain that you have "unbroken" any jobs that you may have "broken" during migration of your snapshot sites by calling the DBMS_JOB.BROKEN procedure.

   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 replication.

   
   

   Note: If you are migrating all of the master's snapshot sites to Oracle8i when the master site is migrated to Oracle8i, in other words, 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" for additional details.

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

Incremental Migration

It is possible to incrementally migrate your replication environment. However, you must carefully analyze the interdependencies between sites to ensure that they will continue to interoperate throughout your migration. Table B-1 describes the conditions that must be met to allow Oracle7 and Oracle8i replication sites to interoperate.

Table B-1 Interoperability in a Replication Environment

Environment	Action	Pre-Requisite
Multimaster	Migrate master site from Oracle7 to Oracle8i.	All other master sites must be Oracle7 Release 7.3.3 or greater.
Master with dependent snapshots	Migrate master site from Oracle7 to Oracle8i.	All dependent snapshot sites must be Oracle7 Release 7.3.4 or greater.
Master with dependent snapshots	Migrate snapshot site from Oracle7 to Oracle8i.	Associated master site must be Oracle7 Release 7.3.3 or greater.

To avoid interoperability problems within a replication environment, it is strongly recommended that if you must perform an incremental migration that you perform it in the following order:

1. Upgrade all of your master sites to Oracle7 Release 7.3.3 or greater and follow the steps in "Preparing Oracle7 Master Sites for Incremental Migration" to prepare your Oracle7 master sites for incremental migration.

2. Incrementally migrate all snapshot sites to Oracle8i.

3. Incrementally migrate all master sites to Oracle8i.

Preparing Oracle7 Master Sites for Incremental Migration

Before beginning incremental migration of Oracle7 master or snapshot sites, your Oracle7 Release 7.3.3 or greater master sites must be configured so that all replication administration and propagation is done within the security context of a single user at each site. Additionally, this primary master replication administrator must have the same username and password at all Oracle7 and Oracle8i sites. Your Oracle7 master sites may already be configured in this manner. If not, you must complete the following steps:

1. Choose a primary master replication administrator for your replication 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. If they do not already exist, you must create the following links for from each master site to all other master sites in the multimaster environment (for a total of 3N(N - 1) links):
   • A public database link, created as SYS, that includes a valid global database name, as well as a USING clause with a valid SQL*Net 2.3 TNS alias.

   • A private database link, created as SYS, that includes a valid global database name, as well as a CONNECT TO clause with the username and password of the primary master replication administrator.

   • A private database link, create as the primary replication administrator, that includes a valid global database name, as well as a CONNECT TO clause with the username and password of the primary master replication administrator.

Incremental Migration of Snapshot Sites

Before you can migrate a snapshot site to Oracle8i, its associated master site must have been upgraded to Oracle7 Release 7.3.3 or greater and the master site must have been fully prepared for incremental migration.

To incrementally migrate your Oracle7 snapshot sites to Oracle8i, complete the following steps:

1. Isolate the snapshot site from the replication environment by stopping all local updates to updateable 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. Stop all propagation from the snapshot site to its master, for example, 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 Oracle8i Migration Utility and execute the catrep.sql and rold_release.sql (where old_release is the previously installed database version) scripts as documented in Oracle8i Migration.

3. Use the Replication Manager setup wizard or execute the appropriate replication management API calls to configure the primary snapshot replication administrator as the replication administrator and propagator for the snapshot site, to configure a receiver account at the associated master, and to create the appropriate links to the master. For Oracle7 master sites your receiver at the master site must be the primary master replication administrator that you prepared in the previous section. If you are using the Replication Manager setup wizard select the customize option to specify this receiver.

4. Using Replication Manager or the appropriate replication management API calls, regenerate snapshot replication support. See "Regenerating Replication Support for an Updateable Snapshot" for more information. Among other activities, generating replication support establishes the registered propagator as the owner of generated objects

5. Using Replication Manager or the appropriate replication management 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 your master site in Step 1, you 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 Oracle8i environment. Unnecessary privileges may also be revoked.

Incremental Migration of Master Sites

Before upgrading a master site from Oracle7 to Oracle8i, you must meet the following conditions:

• All other master sites in a multimaster environment must be running Oracle7 Release 7.3.3 or greater.

• You must have completed the instructions in "Preparing Oracle7 Master Sites for Incremental Migration".

• Any dependent snapshot sites must be running Oracle7 Release 7.3.4 or greater.

To incrementally migrate your Oracle7 master sites to Oracle8i, complete the following steps:

1. Pick a master site to migrate. You should migrate your master definition site 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. To do this you must:
   • Stop updates to the master site by either:

     calling DBMS_REPCAT.SUSPEND_MASTER_ACTIVITY at the master definition site for all master replication groups,

     or by calling DBMS_DEFER_SYS.UNSCHEDULE_EXECUTION (for Oracle7 sites) or DBMS_DEFER_SYS.UNSCHEDULE_PUSH (for Oracle8i sites) at every remote master site and dependent snapshot site, and by preventing update activity at the master site being migrated. You should also refrain from executing any administrative operations at the master definition site that may affect the master site being migrated. 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 it is empty.

   • Stop any refreshes of the dependent snapshot sites from occurring by "breaking" entries in the job queue at each snapshot site that control automated propagation and refreshing at the snapshot sites.

   • For more information on completing the tasks in Step 1 refer to the following sections in Oracle7 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 List". Also see Chapter 7, "Resolving an Error Manually".

4. Migrate the master site using the Oracle7 to Oracle8i Migration Utility and execute the catrep.sql and rold_release.sql (where old_release is the previously installed database version) scripts as documented in Oracle8i Migration.

5. Using the Replication Manager setup wizard or the replication management API, grant your primary master replication administrator Oracle8i Primary Replication Administrator, Propagator, and Receiver privileges for the master site. See "Preparing for Multimaster Replication" for more information. Database links from the primary replication administrator to the primary master replication administrator at all other Oracle7 and Oracle8i master sites should already exist if you prepared your Oracle 7 master site for compatibility with Oracle8i using the directions in "Preparing Oracle7 Master Sites for Incremental Migration".

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" for more information.

7. Using Replication Manager or the replication management API, regenerate replication support for each replicated object. See "Generating Replication Support for Master Group Objects" 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 Oracle8i. For more information, see "Minimizing Data Propagation for Update Conflict Resolution". 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 replication.

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" 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 (for Oracle7 sites) or following the instructions in"Editing a Scheduled Link" (for Oracle8i sites) for all master sites.

10. All snapshots at both Oracle7, Oracle8, and greater snapshot sites will need a full refresh after their master site has been migrated to Oracle8i. Because of the Oracle8 and greater rowid format, the Oracle7 to Oracle8i 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 Oracle8i when the master site is migrated to Oracle8i, (that is, 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" 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 Oracle8i environment. Unnecessary privileges may also be revoked. Be careful not to drop accounts that are needed to maintain any Oracle7 snapshot sites or master sites.

Migration Using Export/ Import

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

To export a full database from Oracle7 Release 7.3.3 or greater and import to Oracle8i, 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. Import the dump file to the Oracle8i database using the Oracle8i import utility under the SYSTEM schema with FULL=y.

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

See the Oracle8i Utilities reference guide for more information.

Upgrading to Primary Key Snapshots

Once a snapshot site and its master have been migrated to Oracle8i, you can upgrade your rowid snapshots to Oracle8i 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 Oracle8i snapshots sites by altering the snapshots to convert them to primary key snapshots. Oracle8i masters that have been altered to log primary key as well as rowid information can support Oracle7 rowid snapshots as well as Oracle8i rowid and primary key snapshots simultaneously to allow for incremental migration.

Primary Key Snapshots Conversion at Master Site(s)

To support primary key snapshots, do the following at the Oracle8i 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 Oracle8i 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 Oracle8i master site has been configured to support primary key snapshots, do the following at the Oracle8 and greater snapshot sites:

1. Isolate the snapshot site from the replication environment by stopping all local updates to updateable 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 Chapter 3, "Snapshot Concepts & Architecture" for more information.

   
   

   Note: Constraints should not be defined on Rowid snapshots.

3. Perform a fast refresh of all snapshots to remove the need for any remaining rowid references in the master snapshot log.

4. Use the ALTER SNAPSHOT command to convert rowid snapshots to primary key snapshots. For complete syntax information, see the book Oracle8i SQL Reference.

5. 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 need to "unbreak" your jobs to resume your replication activity from your snapshot sites.

Features Requiring Migration to Oracle8/Oracle8i

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

1. Replication of LOB data types (Oracle8).

2. Reduced data propagation (Oracle8).
   • Use the min_communication parameter and,

   • the send_old_values and compare_old_values procedures.

3. Parallel propagation of deferred transactions (Oracle8).

4. Global authentication and privileged database links (Oracle8).

5. Validate procedure. (Oracle8)

Additional Information: See Appendix A, "New Features".

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

1. Simple snapshots with subqueries (Oracle8).

2. Master table reorganization procedures (Oracle8).

3. Vertically partitioned snapshots (Oracle8i).

4. Deployment Templates (Oracle8i).

The following features will automatically work in mixed Oracle7 and Oracle8i environments, but only affect 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" for more information.

Obsolete procedures

Procedures that are obsoleted in Oracle8i include:

DBMS_REPCAT.GENERATE_REPLICATION_PACKAGE

DBMS_REPCAT.GENERATE_REPLICATION_TRIGGER

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

---