SharePlex 12.0 - Upgrade Guide

About this Guide

This guide contains instructions for upgrading SharePlex environment. It is intended for administrators, consultants, analysts, and any other IT professionals tasked with upgrading SharePlex™.

Other SharePlex documentation

For the complete SharePlex documentation set, go to https://support.quest.com/shareplex/technical-documents.

View this document in PDF format

You can download, view and save this document in Adobe PDF format. Click Download in the upper right-hand corner of this page. This action downloads the entire publication.

Before you upgrade

This section contains important information that you need to know before you select a SharePlex installer and begin the upgrade procedure.

Gather the Required Information

You will need the following information about the installation that you want to upgrade:

• Location of the SharePlex product directory
• Location of the SharePlex variable-data directory (or directories) in this instance of SharePlex.
• Name of the SharePlex administrator group (that contains the SharePlex administrator user).
• The ORACLE_SID and ORACLE_HOME (Oracle) or the database name (Open Target) associated with the installation you are upgrading. To determine this, look in the default.yaml file in the data sub-directory of the product directory.

• DSN name from var/odbc/ODBC.ini file.

Check interoperability

If you are upgrading some SharePlex installations in a configuration, but not others, view the SharePlex Release Notes for interoperability support between versions. Parameter settings may be required.

Who should perform the upgrade

Some steps in the upgrade procedures require the Administrator authorization level, which normally is only granted to the person or persons designated as the SharePlex Administrators. An upgrade can only be performed by a person who has this authorization and is familiar with SharePlex.

Check for new and deprecated parameters

• Review the release notes and Deprecated Parameters section of the SharePlex Reference Guide to determine if any of the parameters that you are using were deprecated in this release. SharePlex retains backward compatibility of your current parameter settings, including those that are newly deprecated, so that you do not need to stop processes to reconfigure settings. However, you should familiarize yourself with the new parameter or default functionality that replaces a deprecated parameter to determine whether any configuration changes are appropriate.
• Review the What's New in this Release and Enhancements in this release sections of the Release Notes for any new parameters that affect your current configuration. If any upgrade steps are required, they will be noted.

Upgrade on a source system

These requirements apply to SharePlex when it captures from an Oracle or PostgreSQL source database.

Verify inclusion of one-off builds

If you have received one-off builds of SharePlex, confirm that those builds are included as fixes in the new release that you are installing. This applies to Linux/Unix only as applicable.

To verify one-offs:

1. Run the sp-bininfo utility from the util subdirectory of the product directory of your current SharePlex installation.

   $ cd path_to_SharePlex_proddir/util

   $ ./sp-bininfo

2. Compare the CRs of each one-off shown in the sp-bininfo output with the CRs in the Resolved Issues section of the Release Notes that are included with the new SharePlexversion.
3. If any CRs of your one-offs are not shown in the Resolved Issues, the new version does not include that functionality, and you should not proceed with the upgrade. Contact SharePlex support to obtain the missing fixes.

Requirements to support character set conversion for Oracle database as a source

When replicating to an open target (non-Oracle), SharePlex supports replication from any Oracle Unicode character set and the US7ASCII character set. SharePlex posts data to Open Target in the Unicode character set, and therefore if the source data is Unicode or US7ASCII, no conversion on the target is required.

However, if the following are true, conversion is required on the target:

• If the character set of the source data is anything other than Oracle Unicode or US7ASCII, you must install an Oracle client on the target to perform the conversion to Unicode for posting to the target.
• If the data must be posted to the target database in any character set other than Unicode, you must install an Oracle client on the target to perform the conversion and use the target command to identify the target character set for Post to use.
• If you are replicating LOB data, conversion is required regardless of what the source character set is.

To perform conversion with an Oracle client on Linux:

1. Install an Oracle Administrator client on the target system. The client must be the Administrator installation type. The Instant Client and Runtime installation types are not supported.
2. Set ORACLE_HOME to the client installation. Set ORACLE_SID to an alias or a non-existing SID. SharePlex does not use them and a database does not have to be running.
3. Upgrade SharePlex using the Linux/Unix installer for your operating system.
4. Make certain the SP_OPX_NLS_CONVERSION parameter is set to the default of 1.

To perform conversion with an Oracle client on Windows

1. Install an Oracle Administrator client on the target system. The client must be the Administrator installation type. The Instant Client and Runtime installation types are not supported.
2. In the SharePlex Registry key \HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\QuestSoftware\SharePlex\port_number, set ORACLE_HOME to the Oracle client installation location, and set ORACLE_SID to an alias or a non-existing SID. No Oracle database is required. SharePlex only needs to use the client libraries.
3. Upgrade SharePlex using the Windows installer.
4. Make certain the SP_OPX_NLS_CONVERSION parameter is set to the default of 1.

To apply Unicode and US7ASCII data without conversion:

If the source data is Unicode or US7ASCII and you are not replicating LOB data, no conversion or Oracle client is needed. Set the SP_OPX_NLS_CONVERSION parameter to 0 to disable conversion, and then restart Post if it is running.

Download the SharePlex installer

Download the SharePlex Installer

There are different installers for SharePlex based on the type of operating system. This topic helps you understand the differences and the naming conventions used.

Linux and Unix

The SharePlex installer on Linux and Unix, as applicable, is a self-extracting installation file with the extension .tpm.

Oracle and Open Target:

There is a separate SharePlex installer build for each supported platform.

SharePlex-release#-build#-platform-chipset.tpm

For Oracle Solaris (Sun), there is a separate SharePlex installer build for each supported operating system version. If the operating system version that you have is not listed, choose the highest number that is below your version.

SharePlex-release#-build#-platform-version-chipset.tpm

The installer creates a temporary target directory, within the current directory, for extraction. This temporary target directory is removed upon installation completion. You can extract the files to a file system that is separate from the SharePlex installation location by using the -t option when running the .tpm file.

Note: The installation file (.tpm) file for the PostgreSQL database is available only for the Linux platform.

Windows

On Windows, the SharePlex installer is named sp_setup_version.exe. It is a bundle that contains SharePlex binaries for all of the supported databases and versions.

The installer installs the following items:

• The SharePlex binaries and files
• The SharePlex for database program
• The Cygwin environment (default SharePlex\cygwin64)

Note: Cygwin binaries will be present in the SharePlex installation directory.

• Windows registry entries under \HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432node.
• One or more SharePlex port_number Windows services (depending on the installed configuration)

Do not remove or modify any of these components while SharePlex is in production, including SharePlex Installer. These components all support SharePlex operation or upgrade.

Where to get SharePlex installers

Download the SharePlex installation package that matches the operating system you are using.

Additionally, download any SharePlex patches, so that you can install them after you install the base software.

Perform the below steps to download the SharePlex patches:

1. Go to the Quest Software Support page: http://support.quest.com/

2. Click Download Software.

3. In the search box, type SharePlexand press Go.

4. Click the arrow in the Download column for the version you need. You can also click the file name for access to more information and to download the file(s).

5. Transfer the file to system where you are installing SharePlex.

6. You are ready to begin the installation process. Be sure to thoroughly read the version specific Release Notes prior to running the installer.

Upgrade on Linux/Unix for Oracle Database

These instructions are for upgrading SharePlex when configured for an Oracle or PostgreSQL database running on a Linux or Unix system.

To upgrade SharePlex in the current product directory:

1. Log in to the system as the SharePlex installation owner.

2. (If using copy/append) In sp_ctrl on the target systems, stop sp_sync_launcher before applying the SharePlex upgrade.

   sp_ctrl> stop launcher

3. (applicable only for Oracle source) In sp_ctrl on the source system, use the set param command to stop DDL replication by setting the SP_OCT_REPLICATE_ALL_DDL parameter to 0.

   sp_ctrl> set param SP_OCT_REPLICATE_ALL_DDL 0

4. Shut down the SharePlex instance that you are upgrading.

   sp_ctrl> shutdown

   Note: Before shutting down the SharePlex instance, stop the Capture process if your source database is PostgreSQL with logical replication.

5. Verify that all SharePlex processes in that SharePlex instance are stopped, and stop any that are still running.

   # ps -ef | grep sp_

   sp_ctl> stop process

6. (Optional) If you need to upgrade the Oracle or PostgreSQL database, do so now.
7. Tar up the existing SharePlex product directory and move the tar file to different location as a backup.

8. Run the SharePlex installation program.

   1. Log in to the system as the user that will be named as the SharePlex Administrator during this installation. This user will own the installation files and binaries.
   2. If sp_cop is running, shut it down.
      sp_ctrl> shutdown
   3. Copy the installation file to a temporary directory where you have write permissions.
   4. Grant executable permissions to the file.
      #chmod 555installation_file
   5. Run the .tpm file. If installing SharePlex in a cluster, run the installer from the primary node (the one to which the shared disk is mounted)
      # ./installation_file
   6. Verify that the information shown on the first screen corresponds to the version and platform (Oracle or PostgreSQL) you are upgrading.
9. Verify that the information shown on the first prompt corresponds to the version and platform (Oracle or PostgreSQL) that you are upgrading.
10. Follow the prompts to supply the following information:

    Prompt	Input
    Installation type	Select the current product directory of the SharePlex installation you are upgrading.
    SharePlex Admin group	Select the DBA-privileged group to which the SharePlex Administrator user belongs.
    Proceed with upgrade?	Press Enter to confirm the SharePlex environment and proceed with the upgrade.
    License key (do you want to upgrade?)	Press Enter to accept the default of N (no) to keep the existing license, or enter Y to specify a new license key if required for this upgrade.
    Please specify platform for license key (select a number):	Please select the appropriate number from the following list of platforms to install the license key: 1) Oracle 2) File 3) JMS 4) Kafka 5) SQL Server 6) Postgres 7) MySQL 8) Snowflake 9) MariaDB 10) Event Hubs 11) All Platforms q) Quit License Utility Note: To install a trial version of SharePlex, users need to select the All Platforms option.
    License key	(If Y was selected) Enter the new license key that you received from Quest.

    Note: The installer will upgrade the default variable-data directory that is listed in the default.yaml file, which is located in the data sub-directory of the product directory.
    

11. Run the database setup utility for each variable-data directory in the installation of SharePlex that you upgraded. See the SharePlex Installation and Setup Guide to run the various database setups.

12. Start SharePlex using the following syntax with options as appropriate.

    $ cd /productdir/bin

    $ ./sp_cop [-uidentifier] &

    where:

    • -uidentifier starts sp_cop with the unique identifier for the instance you are upgrading, and is only needed if there are multiple instances of sp_cop running on the system.

    Note: After upgrading, to bring up your existing setup, activate the same configuration file again if your source is PostgreSQL with logical replication. This will add newly created SharePlex internal tables to the publication used for logical replication before starting the Capture process.

13. (applicable only for Oracle source) In sp_ctrl on the source system, set the the SP_OCT_REPLICATE_ALL_DDL parameter to 1.

    sp_ctrl> set param SP_OCT_REPLICATE_ALL_DDL 1

To upgrade SharePlex to a new product directory:

2. Shut down sp_cop.

   sp_ctrl> shutdown

2. (Optional) If you need to upgrade the Oracle or PostgreSQL database, do so now.
3. Tar up the existing SharePlex product directory and move the tar file to different location as a backup.
4. Run the SharePlex installer and, when prompted to specify the product directory location, select New Installation.

   You are prompted for the following:
   

   Prompt	Input
   Installation type	Select <New Installation>.
   Product directory location (path)	Enter the path to the SharePlex installation directory. If the specified directory does not exist, the installer creates it. If the directory exists, it must be empty. The installer quits if the directory contains prior SharePlex installations or other files. (Applicable only for Oracle source) In a cluster, install on the shared disk. For more information, see Installation and setup for Oracle cluster in the Installation and Setup Guide document.
   Variable data directory location	Specify an empty directory. The installer creates the specified directory if it does not exist. Important! Do not install this directory into the SharePlex product directory. (Applicable only for Oracle source) In a cluster, install the variable-data directory on the shared disk. For more information, see Installation and setup for Oracle cluster in the Installation and Setup Guide document.
   SharePlex Admin group	Enter the DBA-privileged group to which the SharePlex Administrator user belongs, which will own the SharePlex binaries. If the default group of the SharePlex Administrator is oinstall, select any option, and make certain this user is listed under oinstall in the etc/group file. For more information, see Installer checklist in the Installation and Setup Guide document.
   TCP/IP port for SharePlex	Enter the port number to use for SharePlex TCP/IP communications.
   License key (do you have?)	Press Enter to accept the default of Y (yes). If you do not have a license, enter no. For licensing on a cluster, see Installation and setup for Oracle cluster in the Installation and Setup Guide document. At any point before you run SharePlex you can add the license key with the splex_add_key utility. For more information, see SharePlex license utilities in the Installation and Setup Guide document.
   Please specify platform for license key (select a number):	Please select the appropriate number from the following list of platforms to install the license key: 1) Oracle 2) File 3) JMS 4) Kafka 5) SQL Server 6) Postgres 7) MySQL 8) Snowflake 9) MariaDB 10) Event Hubs 11) All Platforms q) Quit License Utility Note: To install a trial version of SharePlex, users need to select the All Platforms option.
   License key	Enter the license key you received from Quest.

5. Export the SP_SYS_VARDIR environment variable to the existing variable-data directory (not the temporary one) that you want to upgrade.
6. Run the database setup utility using the existing SharePlex database user. See the SharePlex Installation and Setup Guide to run the various database setups.
7. Start sp_cop.
   $ /productdir/bin/sp_cop [-uidentifier] [-s] &