SharePlex 10.1.3 - Installation and Setup for Oracle Source

PostgreSQL Setup (pg_setup)

Overview

Run the Database Setup utility for Postgres (pg_setup) to establish a user account, schema, and tables for use by SharePlex.

Supported databases

All implementations of the Postgres open-source database on supported platforms

Fujitsu Enterprise Postgres Prerequisite

Fujitsu Postgres contains a customized ODBC driver designed to run with the shared libraries supplied by Fujitsu Postgres. In order to ensure the proper configuration, you must create a symbolic link to ensure that the correct libraries are found at runtime.

Issue Description

If you attempt to run the pg_setup program prior to creating the symbolic link, pg_setup will fail with the following error message:

Error: [unixODBC]invalid connection option "target_server"

To create a symbolic link

To ensure that the proper library gets loaded, first locate the path to the directory where the Fujitsu Postgres libraries are installed (for example /opt/fsepv95server64/lib). Then create a symbolic link in the SharePlex OPTDIR/lib/hooks directory pointing to the libpq.so.5 library in the Fujitsu Postgres library directory. For example:

cd /opt/splex/lib/hooks

ln –s /opt/fsepv95server64/lib/libpq.so.5

Guidelines for use

• Run the Database Setup utility on all target Postgres instances in the SharePlex replication configuration.
• Within a server cluster, run the Database Setup utility on the node to which the shared disk that contains the SharePlex variable-data directory is mounted.
• For consolidated replication, run the Database Setup utility for each variable-data directory.
• On Windows, you must supply a DSN (data source name) as the connection method.

• On Linux, you can provide a connection string or a DSN (data source name). Note the following when deciding on the connection method on Linux:

  Connection Type on Linux	What to do
  Connection string	You do not need to provide a user, password, or default database in a connection string. The connection string must have the port, server and driver defined. This is an example from EDB Postgres Plus Advanced Server; your connection string will probably be different based on your own database setup: Port=5444;server=localhost;driver=/u01/PostgresPlus/connectors/odbc/lib/edb-odbc.so;database=edb;
  DSN	If you have a DSN defined, and you want to use it for the SharePlex connection, copy or link the ODBC files in which that DSN is defined (odbc.ini and odbcinst.ini) to the odbc subdirectory of the SharePlex variable-data directory. This prevents connection errors when the SharePlex processes connect to the database. If you do not have a DSN defined but want to use one, you can create it in the template files provided in the odbc subdirectory.

Required privileges

Review the following requirements to ensure that the setup succeeds.

• The Database Setup utility must be run as a Postgres Administrator in order to grant SharePlex the required privileges to operate on the database and to create the SharePlex database account.

• (Symfoware only) If the person who is running the setup utility is not a Fujitsu Enterprise Postgres owner, set the environment variable LD_LIBRARY_PATH to include the path to the lib subdirectory in the Fujitsu Enterprise Postgres installation directory. The LD_LIBRARY_PATH is set in the .bash_profile file of the Fujitsu Enterprise Postgres owner.

  Example:

  export LD_LIBRARY_PATH= /opt/symfoserver64/lib:$LD_LIBRARY_PATH

  If you do not set this path, the following error occurs:

  symbol lookup error: /opt/fsepv95client64/odbc/lib/psqlodbca.so: undefined symbol: PQconnectdbParams

• Cloud installations:
  • Common restrictions on privileges in cloud-hosted database services make it difficult for the setup utility to succeed in every possible type of scenario. To ensure that the database setup succeeds, only use the setup utility for the following purposes: To do a first-time database setup with a new SharePlex user, or, to modify an existing SharePlex user that either owns the database or has access to it.

  • On Amazon RDS, you might need to grant usage/privileges on the target schema and tables to the SharePlex user, as shown in the following example:

    Log in as the schema owner, then issue the following commands:

    grant usage on schema schema_name to user_name;

    grant all privileges on all tables in schema schema_name to user_name;
    

Run Database Setup for PostgreSQL

1. Shut down any running SharePlex processes and sp_cop on the target system.

2. Run the pg_setup program from the bin subdirectory of the SharePlex product directory.

   Important! If you installed the SharePlex instance on any port other than the default of 2100, use the -p option to specify the port number. For example, in the following command the port number is 9400.

   $ /users/splex/bin> pg_setup -p9400

Table 10: Setup prompts and responses

A successful setup terminates with a message similar to the following:

Completed SharePlex for PostgreSQL database configuration

SharePlex User name: splex

Database name: ndb5

Target specification in SharePlex configuration: r.ndb5

Configure SharePlex to support PostgreSQL database on Azure platform

You can configure SharePlex to support the PostgreSQL database on the Azure platform using the below steps:

1. Add the DSN entry in the Odbc.ini file at /etc/odbc.ini and the …/var/odbc directory.
2. Copy the /etc/odbcinst.ini file to the …/var/odbc directory.
3. Run the PostgreSQL setup utility.

Table 11: Setup Prompts and Responses

A successful setup terminates with a message similar to the following:

Completed SharePlex for PostgreSQL database configuration

SharePlex User name: postgres@pslazpgdb02.postgres.database.azure.com

Database name: sp_mk

The data source identifier in the SharePlex configuration is 'r.sp_mk' –

SQL Server Setup (mss_setup)

Overview

Run the Database Setup utility for SQL Server (mss_setup) on a Microsoft SQL Server system to establish SharePlex as a SQL Server database user. This utility creates the following:

• A SharePlex user account with the db_owner role
• Tables and indexes for use by SharePlex and owned by the SharePlex user in a database of your choosing
• A default database connection.

Supported databases

For supported SQL Server platforms and versions, see the SharePlex Release Notes.

Guidelines for use

• A system DSN (data source name) must exist for the SQL Server database. SharePlex Post uses the DSN to connect to the database through ODBC.
• Run the Database Setup utility on all SQL Server instances in the SharePlex replication configuration.
• Within a cluster, run the Database Setup utility on the node to which the shared disk that contains the variable-data directory is mounted.
• For consolidated replication, run the Database Setup utility for each variable-data directory.

Required privileges

Review the following requirements to ensure that the setup succeeds.

• The Database Setup utility must be run as a SQL Server System Administrator in order to grant SharePlex the required privileges to operate on the database and to create the SharePlex database account and objects.

• The sysadmin role is required to run mss_setup, but it is not required by the SharePlex database account used to run SharePlex replication (the SharePlex User). The db_owner role is required by the SharePlex User account and it is granted by mss_setup (for source and target).

• (Cloud installations) Common restrictions on privileges in cloud-hosted database services make it difficult for the setup utility to succeed in every possible type of scenario. To ensure that the database setup succeeds, only use the setup utility for the following purposes: To do a first-time database setup with a new SharePlex user, or, to modify an existing SharePlex user that either owns the database or has access to it.

Run Database Setup for SQL Server

1. Shut down any running SharePlex processes and sp_cop on the SQL Server system.

2. Run the mss_setup program from the bin subdirectory of the SharePlex product directory.

   Important! If you installed the SharePlex instance on any port other than the default of 2100, use the -p option to specify the port number. For example, in the following command the port number is 9400.

   C:\users\splex\bin> mss_setup -p9400

Table 12: Setup prompts and responses

A successful setup terminates with a message similar to the following:

Completed SharePlex for Microsoft SQL Server database configuration

SharePlex User name: splex

Database name: db1

Target specification in SharePlex configuration: r.db1

General SharePlex Utilities

The SharePlex utilities help you configure, test, and manage the SharePlex environment.

Contents

SharePlex license utilities

Description

Use the SharePlex license utilities to view and add license keys to hosts in the SharePlex replication environment. Each installation of SharePlex requires a valid license key. There are three types of SharePlex license keys:

• Temporary license keys (demonstration licenses)
• Permanent license keys
• Site license keys

SharePlex licensing information can be found in the Quest Software Product Guide. Please contact your account manager if you have questions.

If you do not have a valid license key, you may obtain one from Quest Technical Support or your Quest sales representative. Use the appropriate procedure in this documentation to obtain the necessary information to support your license request.

License utilities on Unix and Linux

On Unix and Linux systems, separate utilities are used to:

• Gather information to request a license
• Add a license key
• View a license key

Gather information to request a license

Use the splex_uname utility to collect information about the local host that is required for Quest to generate a license key. Run this utility from the util sub-directory of the SharePlex product directory.

$ /proddir/util/splex_uname

The information is similar to the following example:

Local system info:
Host Name	 	= irvspxu09
Host ID	 	= 2198894273 (831076C1 HEX)
Operating System	= SunOS
Machine model		= SUNW,UltraAX-i2
CPU Type		= sparc9
CPU Speed	 	= 500
Number of CPUs	 	= 1

Add a license key

Use the splex_add_key utility to add a license key to a machine during the installation of SharePlex or afterward to convert from one type of license to another.

You can use the splex_add_key utility as follows:

• You can use splex_add_key on the primary node of a cluster to install licenses for all secondary nodes in the cluster, because they all share one variable-data directory.
• You cannot use splex_add_key to add licenses for non-clustered machines from one machine. It must be run on each non-clustered replication system so that the license information is stored in the variable-data directory on each system.

To run splex_add_key

1. Log on to the system as the SharePlex Administrator.
2. Run sp_ctrl on the machine where you want to install a license key.

3. If SharePlex is running, shut it down.

   sp_ctrl> shutdown

4. Run splex_add_key from the install sub-directory of the SharePlex product directory.

   $ /proddir/install/splex_add_key

5. Choose the appropriate option for how to install the key:

   SharePlex License Utility
   1) Read license key from file
   2) Enter license key manually
   3) Add license key for alternate host
   q) Quit License Utility
   Enter option:

   Note: Use option 3 when installing on secondary nodes in a cluster. To install SharePlex in a cluster, see "Preinstallation instructions for Oracle cluster" in the SharePlex Installation and Setup Guide for Oracle.

6. If you are entering the key manually, type the license key exactly as you received it from Quest, including the SPLEXKEY= string if one prepends the key, any spaces, and any capitalization. Press Enter when finished typing the key.

7. Enter the SiteMessage text string provided by Quest with the license key.

   Note: If you selected option 3 to install in a cluster, the utility continually prompts for another machine ID to license, until you exit the license utility.

8. Enter q to exit the utility.
9. Start SharePlex when you are ready for replication to resume.

View a license key

Use the splex_get_key utility to view the SharePlex license key, license type, and expiration date on a machine. Run this utility from the install sub-directory of the SharePlex product directory.

$ /proddir/install/splex_get_key

The information is similar to the following example:

$ /splex/proddir/install/splex_get_key
Customer Name = Quest
License Key = EANLCF3P56F8M1JB1K6RBJCBB6TBEP0
Product Name = SharePlex Oracle
License type = demo key
Expired on = 01/01/2008 12:00 AM

License utility on Windows

On Windows platforms, all licensing functions are performed through the SpUtils utility, including viewing the machine ID for a system. Launch the SpUtils utility from the shortcut on the Windows desktop.

Gather information to request a license

Select the Information tab to view information about the local host that is required for Quest to generate a license key. In a cluster, run SpUtils on each node.

Add a license key

Use SpUtils to add a license key to a machine during the installation of SharePlex or afterward to convert from one type of license to another. In a cluster, run SpUtils on the primary node.

1. Log on to Windows as the SharePlex Administrator.

2. If SharePlex is running, do the following:

   1. Select the SharePlex Services tab.
   2. Select the port number of the SharePlex instance for which you want to add a license key.
   3. Click Stop.
   4. Wait for Current State to display a message that the service stopped.
3. Select the License Keys tab.

4. Select the SharePlex port number from the Port list.

5. Click Add License, then type or paste the information exactly as you received it from Quest, as follows:

   1. License Key: The license key, including any spaces. The key is case-sensitive.
   2. Customer Name: The text string that was included with the license. The name is case-sensitive.

6. (Windows Cluster) To add a license for another node in a cluster, select the Add Alternate Host Id check box, then select the machine ID from the CPU ID list box. Repeat this step to add a license to all secondary nodes in the cluster.

7. Click OK to close the utility.

8. To start SharePlex, do the following:

   1. Select the SharePlex Services tab.
   2. Select the port number of the SharePlex instance that you licensed.
   3. Click Start.
   4. Wait for Current State to display a message that the service started.

View a license key

Select the License Key tab, then select the port number (if running multiple SharePlex instances) for which you want to view license information.

• Under License Key, view the actual license key and SiteMessage text string.
• Under Status, view the type of SharePlex installation, the license type, and the expiration date.

In a cluster, run SpUtils on each node to view the local license.