Upgrading the Replication Agent for Oracle from LogMiner to XStream

To upgrade the Replication Agent for Oracle Log Reader component from LogMiner to XStream APIs, use the ra_admin command with the -u option.

Prerequisites

  • Make sure the primary database version is Oracle11.2.0.3 or later.

  • Initialize the Replication Agent.

  • Set the Oracle library path and the XStream JDBC driver in the CLASSPATH environment variable for your platform. See Setting Up the Oracle XStream JDBC Driver.
  • Shut down the Replication Agent instance and make sure no database operations are running to avoid risking data loss due to missed replication.
Note: You cannot downgrade to LogMiner once you have upgraded the Replication Agent Log Reader to use XStream APIs.
Task
  1. To use maximum-strength password encryption, install Java Cryptography Extension (JCE) policy files and reset the system administrator account.

    See Installing Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 7.

  2. Set the SYBASE environment variable by changing the SYBASE directory in which Replication Agent is installed.

    • For C Shell: source SYBASE.csh

    • For Bourne or Korn shell: . SYBASE.sh

    • For Windows, run: SYBASE.bat

  3. Change to the Replication Agent bin directory using the command line prompt:

    • On UNIX: 

      cd $SYBASE/RAX-15_5/bin

    • On Windows:

      cd %SYBASE%\RAX-15_5\bin
  4. Upgrade the Replication Agent instances to use Oracle XStream APIs.
    Option Description
    Upgrading instances within the same product installation
    • To upgrade a specific Replication Agent instance in the Replication Agent installation directory, at the command prompt, run:
      On UNIX:
       ./ra_admin.sh -u instance=<instance_name> -t oraclexs
      On Windows:
      ra_admin.bat -u instance=<instance_name> -t oraclexs
    • To upgrade all Replication Agent instances in the Replication Agent installation directory, at the command prompt, run:
      ./ra_admin.sh -u all -t oraclexs
      ra_admin.bat -u all -t oraclexs
      Note: Because the current version upgrade is not supported, you cannot upgrade the Replication Agent for Oracle 15.7.1 SP120 Log Reader component from LogMiner to use XStream APIs.
    Upgrading instances in a separate product installation
    • To upgrade a specific Replication Agent instance in the specified source instance directory from the current product installation directory, run:
      On UNIX:
       ./ra_admin.sh -u <source_instance_directory> -t oraclexs
      On Windows:
      ra_admin.bat -u <source_instance_directory> -t oraclexs
    • To upgrade all Replication Agent instances in the specified source installation directory from the current product installation directory, at the command prompt, run:
      ./ra_admin.sh -u <source_installation_directory>
      ra_admin.bat -u <source_installation_directory>

    If the Oracle primary database version is earlier than 11.2.0.3, the upgrade process stops and shows: "The Replication Agent upgrade is not supported on <instance_name> for database version <xx.xx.xx.xx>. The minimum database version supported to upgrade Replication Agent from LogMiner to XStream APIs is:11.2.0.3."

    In the commands above:

    • all – upgrades all instances of Replication Agent within the current product installation directory except the Replication Agent 15.7.1 SP120 instance with the LogMiner component. The configuration files are backed up before the upgrade. If an error occurs, the upgrade is rolled back.

    • instance_name – is the name of the Replication Agent instance to be upgraded.

      When you enter instance_name, the upgrade is performed directly on the specified instance. The configuration file is backed up before the upgrade for use in error recovery, if required. If an error occurs, the upgrade is rolled back.

    • source_installation_directory – is the Replication Agent source installation directory.

      When you enter the source_installation_directory, all instances of Replication Agent in the specified source installation directory are upgraded from the current product installation directory provided the earlier version of the Replication Agent instance uses LogMiner component to read from the transaction logs. The instance is first copied to and then updated within the current product installation directory

    • oraclexs – is the Oracle XStream database type.

      When you enter -t oraclexs, the Log Reader component is upgraded from LogMiner to Oracle XStream APIs.

  5. Start the Replication Agent instance.
    On UNIX:
    $SYBASE/RAX-15_5/<instance>/RUN_<instance>
    On Windows:
    %SYBASE%\RAX-15_5\<instance>\RUN_<instance>
    where instance is the Replication Agent instance name.
  6. Log in to the Replication Agent instance and migrate the metadata by running:
    ra_migrate

    This command initiates the upgrade process, finalizes the upgrade of an instance from an earlier version, and prevents a subsequent downgrade to the earlier version.

    During upgrade, Replication Agent creates an XStream outbound server with the current start system change number (SCN) to read from transactions logs.

  7. Once the Replication Agent is upgraded, set the Oracle environment variables for XStream APIs.
  8. Execute the Replication Server System Database (RSSD) rs_zeroltm command at the primary database connection to reset the LTM locator value to zero.

    Run rs_zeroltm before resuming replication, to prevent Replication Server from requesting a log starting point that occurs earlier in the log than the location established by the ra_migrate option. The Replication Server LTM locator value for the primary connection must be zeroed.

    For example: 
    rs_zeroltm data_server, database
  9. Resume replication.
    resume

    Before resuming replication, wait for the upgrade process to complete. Otherwise, data inserted during upgrade is not replicated.

Parent topic: Oracle XStream